package com.hexingmo.dawn.lang;

import com.hexingmo.dawn.lang.exception.NetworkException;

import javax.net.ssl.HttpsURLConnection;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.math.BigInteger;
import java.net.HttpURLConnection;
import java.net.Inet4Address;
import java.net.Inet6Address;
import java.net.InetAddress;
import java.net.InetSocketAddress;
import java.net.NetworkInterface;
import java.net.Socket;
import java.net.SocketException;
import java.net.SocketTimeoutException;
import java.net.URL;
import java.net.UnknownHostException;
import java.nio.charset.StandardCharsets;
import java.security.cert.Certificate;
import java.util.ArrayList;
import java.util.Enumeration;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import java.util.function.Predicate;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Collectors;

/**
 * 网络工具类，提供兼容不同地区的网络连接检测
 *
 * @author He Xing Mo
 * @since 1.0
 */
public class NetworkUtils {

    public static final String LOCAL_LOOPBACK_V4_IP = "127.0.0.1";
    
    public static final Pattern DOMAIN_PATTERN = Pattern.compile(
        "^[a-zA-Z0-9]([a-zA-Z0-9\\-]{0,61}[a-zA-Z0-9])?(\\.[a-zA-Z0-9]([a-zA-Z0-9\\-]{0,61}[a-zA-Z0-9])?)*$"
    );

    public static final Pattern IPV6_PATTERN = Pattern.compile(
        "^([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}$|" +
        "^([0-9a-fA-F]{1,4}:){1,7}:$|" +
        "^([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}$|" +
        "^([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}$|" +
        "^([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}$|" +
        "^([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}$|" +
        "^([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}$|" +
        "^[0-9a-fA-F]{1,4}:(:[0-9a-fA-F]{1,4}){1,6}$|" +
        "^:((:[0-9a-fA-F]{1,4}){1,7}|:)$|" +
        "^fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}$|" +
        "^::(ffff(:0{1,4}){0,1}:){0,1}((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])$|" +
        "^([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])$"
    );

    /**
     * MAC地址正则表达式模式
     *
     * 支持的格式：
     * - 标准格式：AA:BB:CC:DD:EE:FF
     * - 连字符格式：AA-BB-CC-DD-EE-FF
     * - 点分隔格式：AA.BB.CC.DD.EE.FF
     * - 空格分隔格式：AA BB CC DD EE FF
     * - 无分隔符格式：AABBCCDDEEFF
     * - 小写格式：aa:bb:cc:dd:ee:ff
     * - 混合大小写：Aa:Bb:Cc:Dd:Ee:Ff
     */
    public static final Pattern MAC_ADDRESS_PATTERN = Pattern.compile(
            "^([0-9A-Fa-f]{2}[:-]?){5}[0-9A-Fa-f]{2}$|" +
            "^([0-9A-Fa-f]{2}[.]?){5}[0-9A-Fa-f]{2}$|" +
            "^([0-9A-Fa-f]{2}\\s?){5}[0-9A-Fa-f]{2}$|" +
            "^[0-9A-Fa-f]{12}$"
    );

    /**
     * MAC地址严格模式正则表达式模式（支持Windows和Linux标准格式）
     * 
     * 支持的格式：
     * - Windows标准格式：AA-BB-CC-DD-EE-FF
     * - Linux标准格式：AA:BB:CC:DD:EE:FF
     * - 每个字节必须是两位十六进制数字
     * - 不允许混合使用不同分隔符
     * - 不允许无分隔符格式
     */
    public static final Pattern MAC_ADDRESS_STRICT_PATTERN = Pattern.compile(
            "^([0-9A-Fa-f]{2}[:-]){5}[0-9A-Fa-f]{2}$"
    );

    private NetworkUtils() {
        throw new IllegalStateException("Static utility classes do not support instantiation");
    }
    

    /**
     * 检测是否可以访问互联网（兼容不同地区）
     * 
     * 网络连接检测原理：
     * - 通过尝试连接多个不同地区的网站来判断网络连通性
     * - 优先测试中国地区的网站，然后测试全球性网站
     * - 使用ICMP ping方式检测，避免HTTP连接可能被防火墙阻止
     * 
     * 测试网站说明：
     * - 中国地区：百度、腾讯、淘宝、网易、新浪
     * - 全球性：Google、Facebook、微软、苹果、亚马逊
     * 
     * 使用场景：
     * - 应用启动时检查网络状态
     * - 网络功能使用前的连通性验证
     * - 网络故障诊断
     * 
     * 使用示例：
     * // 检查网络连接
     * if (NetworkUtils.hasInternetConnection()) {
     *     System.out.println("网络连接正常");
     *     // 执行需要网络的操作
     * } else {
     *     System.out.println("网络连接异常");
     *     // 显示离线模式或错误提示
     * }
     * 
     * 相关文档：
     * - IPv4: https://tools.ietf.org/html/rfc791
     * - IPv6: https://tools.ietf.org/html/rfc8200
     * - ICMP: https://tools.ietf.org/html/rfc792
     * 
     * @return true表示可以访问互联网，false表示无法访问
     */
    public static boolean hasInternetConnection() {
        return hasInternetConnection(5000);
    }

    /**
     * 检测是否可以访问互联网（指定超时时间）
     * 
     * 超时设置说明：
     * - 默认超时时间：5000毫秒（5秒）
     * - 建议超时范围：3000-10000毫秒
     * - 超时时间过短可能导致误判
     * - 超时时间过长影响用户体验
     * 
     * 使用示例：
     * // 快速检测（3秒超时）
     * boolean quickCheck = NetworkUtils.hasInternetConnection(3000);
     * 
     * // 详细检测（10秒超时）
     * boolean detailedCheck = NetworkUtils.hasInternetConnection(10000);
     * 
     * @param timeoutMillis 超时时间（毫秒），建议3000-10000
     * @return true表示可以访问互联网，false表示无法访问
     */
    public static boolean hasInternetConnection(int timeoutMillis) {
        // 定义多个可访问的网站，按优先级排序
        String[] testUrls = {
                "www.baidu.com",      // 百度（中国）
                "www.qq.com",         // 腾讯（中国）
                "www.taobao.com",     // 淘宝（中国）
                "www.163.com",        // 网易（中国）
                "www.sina.com.cn",    // 新浪（中国）
                "www.google.com",     // Google（全球）
                "www.facebook.com",   // Facebook（全球）
                "www.microsoft.com",  // 微软（全球）
                "www.apple.com",      // 苹果（全球）
                "www.amazon.com"      // 亚马逊（全球）
        };

        for (String url : testUrls) {
            try {
                InetAddress address = InetAddress.getByName(url);
                if (address.isReachable(timeoutMillis)) {
                    return true;
                }
            } catch (Exception e) {
                // 继续尝试下一个URL
                continue;
            }
        }

        return false;
    }

    /**
     * 检测是否可以访问互联网（使用DNS查询方式）
     * 
     * DNS检测原理：
     * - 通过尝试连接多个公共DNS服务器来判断网络连通性
     * - DNS查询是网络连接的基础，通常不会被防火墙阻止
     * - 相比HTTP检测，DNS检测更快速且更可靠
     * 
     * 测试DNS服务器说明：
     * - Google DNS: 8.8.8.8, 8.8.4.4 (全球最稳定)
     * - 中国DNS: 114.114.114.114, 223.5.5.5, 119.29.29.29
     * - 国际DNS: 1.1.1.1 (Cloudflare), 208.67.222.222 (OpenDNS)
     * 
     * 使用场景：
     * - 快速网络连通性检测
     * - 防火墙环境下的网络检测
     * - DNS服务可用性验证
     * 
     * 使用示例：
     * // DNS方式检测网络
     * if (NetworkUtils.hasInternetConnectionByDNS()) {
     *     System.out.println("DNS服务正常，网络连接可用");
     * } else {
     *     System.out.println("DNS服务异常，可能存在网络问题");
     * }
     * 
     * 相关文档：
     * - DNS: https://tools.ietf.org/html/rfc1035
     * - DNS over HTTPS: https://tools.ietf.org/html/rfc8484
     * - Google Public DNS: https://developers.google.com/speed/public-dns
     * 
     * @return true表示DNS服务可用，false表示DNS服务不可用
     */
    public static boolean hasInternetConnectionByDNS() {
        return hasInternetConnectionByDNS(3000);
    }

    /**
     * 检测是否可以访问互联网（使用DNS查询方式，指定超时时间）
     * 
     * 超时设置建议：
     * - DNS查询通常很快，建议超时时间：1000-5000毫秒
     * - 默认超时时间：3000毫秒（3秒）
     * - 超时时间过短可能导致误判
     * 
     * 使用示例：
     * // 快速DNS检测（1秒超时）
     * boolean quickDNS = NetworkUtils.hasInternetConnectionByDNS(1000);
     * 
     * // 详细DNS检测（5秒超时）
     * boolean detailedDNS = NetworkUtils.hasInternetConnectionByDNS(5000);
     * 
     * @param timeoutMillis 超时时间（毫秒），建议1000-5000
     * @return true表示DNS服务可用，false表示DNS服务不可用
     */
    public static boolean hasInternetConnectionByDNS(int timeoutMillis) {
        // 使用DNS服务器进行测试
        String[] dnsServers = {
                "8.8.8.8",        // Google DNS
                "8.8.4.4",        // Google DNS备用
                "114.114.114.114", // 114 DNS（中国）
                "223.5.5.5",      // 阿里DNS（中国）
                "119.29.29.29",   // 腾讯DNS（中国）
                "1.1.1.1",        // Cloudflare DNS
                "208.67.222.222"  // OpenDNS
        };

        for (String dnsServer : dnsServers) {
            try {
                InetAddress address = InetAddress.getByName(dnsServer);
                if (address.isReachable(timeoutMillis)) {
                    return true;
                }
            } catch (Exception e) {
                // 继续尝试下一个DNS服务器
                continue;
            }
        }

        return false;
    }

    /**
     * 检测是否可以访问互联网（使用HTTP连接方式）
     * 
     * HTTP检测原理：
     * - 通过HTTP HEAD请求测试网站的可访问性
     * - HEAD请求只获取响应头，不下载内容，速度较快
     * - 可以检测HTTP代理、防火墙等网络配置
     * 
     * 测试网站说明：
     * - 中国地区：百度、腾讯、淘宝、网易、新浪
     * - 全球性：Google、微软、苹果
     * - 使用HEAD方法，减少数据传输量
     * 
     * 响应码说明：
     * - 2xx (成功)：网站可访问
     * - 3xx (重定向)：网站可访问，但需要重定向
     * - 4xx/5xx (错误)：网站不可访问
     * 
     * 使用场景：
     * - HTTP服务可用性检测
     * - 代理服务器配置验证
     * - Web应用网络连通性测试
     * 
     * 使用示例：
     * // HTTP方式检测网络
     * if (NetworkUtils.hasInternetConnectionByHTTP()) {
     *     System.out.println("HTTP服务正常，可以访问网站");
     * } else {
     *     System.out.println("HTTP服务异常，可能存在网络或代理问题");
     * }
     * 
     * 相关文档：
     * - HTTP/1.1: https://tools.ietf.org/html/rfc7231
     * - HTTP/2: https://tools.ietf.org/html/rfc7540
     * - HTTP状态码: https://tools.ietf.org/html/rfc7231#section-6
     * 
     * @return true表示HTTP服务可用，false表示HTTP服务不可用
     */
    public static boolean hasInternetConnectionByHTTP() {
        return hasInternetConnectionByHTTP(5000);
    }

    /**
     * 检测是否可以访问互联网（使用HTTP连接方式，指定超时时间）
     * 
     * 超时设置说明：
     * - HTTP连接需要建立TCP连接，建议超时时间：3000-10000毫秒
     * - 默认超时时间：5000毫秒（5秒）
     * - 包含连接超时和读取超时
     * 
     * 使用示例：
     * // 快速HTTP检测（3秒超时）
     * boolean quickHTTP = NetworkUtils.hasInternetConnectionByHTTP(3000);
     * 
     * // 详细HTTP检测（10秒超时）
     * boolean detailedHTTP = NetworkUtils.hasInternetConnectionByHTTP(10000);
     * 
     * @param timeoutMillis 超时时间（毫秒），建议3000-10000
     * @return true表示HTTP服务可用，false表示HTTP服务不可用
     */
    public static boolean hasInternetConnectionByHTTP(int timeoutMillis) {
        // 定义多个HTTP测试URL
        String[] httpUrls = {
                "http://www.baidu.com",
                "http://www.qq.com",
                "http://www.taobao.com",
                "http://www.163.com",
                "http://www.sina.com.cn",
                "http://www.google.com",
                "http://www.microsoft.com",
                "http://www.apple.com"
        };

        for (String url : httpUrls) {
            try {
                URL testUrl = new URL(url);
                HttpURLConnection connection = (HttpURLConnection) testUrl.openConnection();
                connection.setRequestMethod("HEAD");
                connection.setConnectTimeout(timeoutMillis);
                connection.setReadTimeout(timeoutMillis);
                connection.setInstanceFollowRedirects(false);

                int responseCode = connection.getResponseCode();
                connection.disconnect();

                // 任何2xx或3xx响应码都表示网络连接正常
                if (responseCode >= 200 && responseCode < 400) {
                    return true;
                }
            } catch (Exception e) {
                // 继续尝试下一个URL
                continue;
            }
        }

        return false;
    }

    /**
     * 检测特定网站的可访问性
     * 
     * 网站可访问性检测原理：
     * - 使用ICMP ping方式检测目标主机的可达性
     * - 自动处理URL格式，提取主机名部分
     * - 支持带协议前缀和不带协议前缀的URL
     * 
     * URL处理说明：
     * - 自动移除 http:// 或 https:// 前缀
     * - 自动移除路径部分，只检测主机名
     * - 支持域名和IP地址格式
     * 
     * 使用场景：
     * - 特定网站连通性检测
     * - 服务器状态监控
     * - 网络故障定位
     * 
     * 使用示例：
     * // 检测百度网站可访问性
     * if (NetworkUtils.isWebsiteAccessible("www.baidu.com")) {
     *     System.out.println("百度网站可以访问");
     * } else {
     *     System.out.println("百度网站无法访问");
     * }
     * 
     * // 检测带协议的URL
     * if (NetworkUtils.isWebsiteAccessible("https://www.google.com")) {
     *     System.out.println("Google网站可以访问");
     * }
     * 
     * // 检测带路径的URL
     * if (NetworkUtils.isWebsiteAccessible("https://github.com/username/repo")) {
     *     System.out.println("GitHub可以访问");
     * }
     * 
     * 相关文档：
     * - ICMP: https://tools.ietf.org/html/rfc792
     * - URL格式: https://tools.ietf.org/html/rfc3986
     * - 域名系统: https://tools.ietf.org/html/rfc1035
     * 
     * @param url 要检测的网站URL或域名
     * @return true表示网站可访问，false表示网站不可访问
     */
    public static boolean isWebsiteAccessible(String url) {
        return isWebsiteAccessible(url, 5000);
    }

    /**
     * 检测特定网站的可访问性（指定超时时间）
     * 
     * 超时设置建议：
     * - 本地网络：1000-3000毫秒
     * - 国内网络：3000-5000毫秒
     * - 国际网络：5000-10000毫秒
     * 
     * 使用示例：
     * // 快速检测本地服务器
     * boolean localServer = NetworkUtils.isWebsiteAccessible("192.168.1.100", 1000);
     * 
     * // 检测国际网站
     * boolean internationalSite = NetworkUtils.isWebsiteAccessible("www.google.com", 10000);
     * 
     * @param url 要检测的网站URL或域名
     * @param timeoutMillis 超时时间（毫秒），建议1000-10000
     * @return true表示网站可访问，false表示网站不可访问
     */
    public static boolean isWebsiteAccessible(String url, int timeoutMillis) {
        try {
            // 移除协议前缀
            String host = url;
            if (url.startsWith("http://")) {
                host = url.substring(7);
            } else if (url.startsWith("https://")) {
                host = url.substring(8);
            }

            // 移除路径部分
            int pathIndex = host.indexOf('/');
            if (pathIndex > 0) {
                host = host.substring(0, pathIndex);
            }

            InetAddress address = InetAddress.getByName(host);
            return address.isReachable(timeoutMillis);
        } catch (Exception e) {
            return false;
        }
    }

    /**
     * 检测HTTP网站的可访问性
     * 
     * HTTP网站可访问性检测原理：
     * - 使用HTTP HEAD请求检测网站的可访问性
     * - HEAD请求只获取响应头，不下载内容，效率较高
     * - 可以检测HTTP状态码，判断网站的具体状态
     * 
     * 响应码说明：
     * - 2xx (成功)：网站正常运行
     * - 3xx (重定向)：网站可访问，但需要重定向
     * - 4xx (客户端错误)：请求错误，但服务器可达
     * - 5xx (服务器错误)：服务器内部错误
     * 
     * 协议处理说明：
     * - 自动添加 http:// 前缀（如果未提供）
     * - 支持 http:// 和 https:// 协议
     * - 不跟随重定向，避免无限循环
     * 
     * 使用场景：
     * - Web服务可用性检测
     * - API服务状态监控
     * - 网站响应时间测试
     * 
     * 使用示例：
     * // 检测HTTP网站
     * if (NetworkUtils.isHttpWebsiteAccessible("www.baidu.com")) {
     *     System.out.println("百度网站HTTP服务正常");
     * } else {
     *     System.out.println("百度网站HTTP服务异常");
     * }
     * 
     * // 检测HTTPS网站
     * if (NetworkUtils.isHttpWebsiteAccessible("https://www.google.com")) {
     *     System.out.println("Google网站HTTPS服务正常");
     * }
     * 
     * // 检测API服务
     * if (NetworkUtils.isHttpWebsiteAccessible("https://api.github.com")) {
     *     System.out.println("GitHub API服务正常");
     * }
     * 
     * 相关文档：
     * - HTTP/1.1: https://tools.ietf.org/html/rfc7231
     * - HTTP状态码: https://tools.ietf.org/html/rfc7231#section-6
     * - HTTPS: https://tools.ietf.org/html/rfc2818
     * 
     * @param url 要检测的网站URL或域名
     * @return true表示HTTP服务可访问，false表示HTTP服务不可访问
     */
    public static boolean isHttpWebsiteAccessible(String url) {
        return isHttpWebsiteAccessible(url, 5000);
    }

    /**
     * 检测HTTP网站的可访问性（指定超时时间）
     * 
     * 超时设置说明：
     * - 连接超时：建立TCP连接的时间
     * - 读取超时：等待HTTP响应的时间
     * - 建议总超时时间：3000-15000毫秒
     * 
     * 使用示例：
     * // 快速检测本地Web服务
     * boolean localWeb = NetworkUtils.isHttpWebsiteAccessible("localhost:8080", 2000);
     * 
     * // 检测慢速网站
     * boolean slowSite = NetworkUtils.isHttpWebsiteAccessible("www.slow-site.com", 15000);
     * 
     * @param url 要检测的网站URL或域名
     * @param timeoutMillis 超时时间（毫秒），建议3000-15000
     * @return true表示HTTP服务可访问，false表示HTTP服务不可访问
     */
    public static boolean isHttpWebsiteAccessible(String url, int timeoutMillis) {
        try {
            // 确保URL有协议前缀
            String fullUrl = url;
            if (!url.startsWith("http://") && !url.startsWith("https://")) {
                fullUrl = "http://" + url;
            }

            URL testUrl = new URL(fullUrl);
            HttpURLConnection connection = (HttpURLConnection) testUrl.openConnection();
            connection.setRequestMethod("HEAD");
            connection.setConnectTimeout(timeoutMillis);
            connection.setReadTimeout(timeoutMillis);
            connection.setInstanceFollowRedirects(false);

            int responseCode = connection.getResponseCode();
            connection.disconnect();

            // 任何2xx或3xx响应码都表示网站可访问
            return responseCode >= 200 && responseCode < 400;
        } catch (Exception e) {
            return false;
        }
    }

    /**
     * 异步检测网络连接
     */
    public static CompletableFuture<Boolean> hasInternetConnectionAsync() {
        return CompletableFuture.supplyAsync(() -> hasInternetConnection());
    }

    /**
     * 异步检测网络连接（指定超时时间）
     */
    public static CompletableFuture<Boolean> hasInternetConnectionAsync(int timeoutMillis) {
        return CompletableFuture.supplyAsync(() -> hasInternetConnection(timeoutMillis));
    }

    /**
     * 检测网络连接类型
     * 
     * 网络类型检测原理：
     * - 通过分析网络接口名称来判断网络连接类型
     * - 基于常见的网络接口命名规则进行识别
     * - 支持WIFI、以太网、移动网络等常见类型
     * 
     * 网络类型说明：
     * - WIFI: 无线局域网连接
     * - ETHERNET: 有线以太网连接
     * - MOBILE: 移动网络连接（4G/5G等）
     * - UNKNOWN: 未知或无法识别的网络类型
     * 
     * 接口名称匹配规则：
     * - WIFI: 包含 "wlan" 或 "wifi" 的接口名
     * - ETHERNET: 包含 "eth" 或 "ethernet" 的接口名
     * - MOBILE: 包含 "ppp" 或 "mobile" 的接口名
     * 
     * 使用场景：
     * - 网络类型识别和统计
     * - 根据网络类型调整应用行为
     * - 网络质量评估
     * - 用户体验优化
     * 
     * 使用示例：
     * // 检测当前网络类型
     * String networkType = NetworkUtils.getNetworkType();
     * switch (networkType) {
     *     case "WIFI":
     *         System.out.println("当前使用WIFI网络");
     *         // 可以执行大流量操作
     *         break;
     *     case "ETHERNET":
     *         System.out.println("当前使用有线网络");
     *         // 网络最稳定
     *         break;
     *     case "MOBILE":
     *         System.out.println("当前使用移动网络");
     *         // 注意流量消耗
     *         break;
     *     default:
     *         System.out.println("未知网络类型");
     *         break;
     * }
     * 
     * // 根据网络类型调整下载策略
     * if ("WIFI".equals(NetworkUtils.getNetworkType())) {
     *     // WIFI环境下允许大文件下载
     *     downloadManager.setMaxFileSize(100 * 1024 * 1024); // 100MB
     * } else if ("MOBILE".equals(NetworkUtils.getNetworkType())) {
     *     // 移动网络下限制下载大小
     *     downloadManager.setMaxFileSize(10 * 1024 * 1024); // 10MB
     * }
     * 
     * 相关文档：
     * - 网络接口: https://docs.oracle.com/javase/8/docs/api/java/net/NetworkInterface.html
     * - 网络类型: https://developer.android.com/reference/android/net/ConnectivityManager
     * - WIFI标准: https://standards.ieee.org/standard/802_11-2016.html
     * 
     * @return 网络类型字：WIFI、ETHERNET、MOBILE、UNKNOWN
     */
    public static NetworkType getNetworkType() {
        try {
            Enumeration<NetworkInterface> interfaces = NetworkInterface.getNetworkInterfaces();
            while (interfaces.hasMoreElements()) {
                NetworkInterface networkInterface = interfaces.nextElement();
                if (networkInterface.isUp() && !networkInterface.isLoopback()) {
                    String name = networkInterface.getName().toLowerCase();
                    if (name.contains("wlan") || name.contains("wifi")) {
                        return NetworkType.WIFI;
                    } else if (name.contains("eth") || name.contains("ethernet")) {
                        return NetworkType.ETHERNET;
                    } else if (name.contains("ppp") || name.contains("mobile")) {
                        return NetworkType.MOBILE;
                    }
                }
            }
        } catch (Exception e) {
            // 忽略异常
        }
        return NetworkType.UNKNOWN;
    }
    
    /**
     * 获取所有网络接口的IP地址
     */
    public static String[] getAllLocalIPAddresses() {
        try {
            Enumeration<NetworkInterface> interfaces = NetworkInterface.getNetworkInterfaces();
            java.util.List<String> ipAddresses = new java.util.ArrayList<>();
            
            while (interfaces.hasMoreElements()) {
                NetworkInterface networkInterface = interfaces.nextElement();
                if (networkInterface.isUp() && !networkInterface.isLoopback()) {
                    Enumeration<InetAddress> addresses = networkInterface.getInetAddresses();
                    while (addresses.hasMoreElements()) {
                        InetAddress address = addresses.nextElement();
                        if (!address.isLoopbackAddress() && address.getHostAddress().indexOf(':') == -1) {
                            ipAddresses.add(address.getHostAddress());
                        }
                    }
                }
            }
            
            return ipAddresses.toArray(new String[0]);
        } catch (Exception e) {
            return new String[]{"127.0.0.1"};
        }
    }

    /**
     * 检测端口是否开放
     * 
     * 端口检测原理：
     * - 尝试建立TCP连接到指定主机的指定端口
     * - 如果连接成功，说明端口开放
     * - 如果连接失败，说明端口关闭或被防火墙阻止
     * 
     * 端口类型说明：
     * - 系统端口（0-1023）：需要管理员权限，如80(HTTP)、443(HTTPS)、22(SSH)
     * - 用户端口（1024-49151）：应用程序常用端口
     * - 动态端口（49152-65535）：临时分配端口
     * 
     * 常见端口：
     * - 80: HTTP服务
     * - 443: HTTPS服务
     * - 22: SSH服务
     * - 21: FTP服务
     * - 3306: MySQL数据库
     * - 5432: PostgreSQL数据库
     * - 6379: Redis缓存
     * - 8080: 常用Web服务端口
     * 
     * 使用场景：
     * - 服务器端口可用性检测
     * - 网络服务监控
     * - 防火墙配置验证
     * - 网络故障诊断
     * 
     * 使用示例：
     * // 检测Web服务器端口
     * if (NetworkUtils.isPortOpen("www.example.com", 80)) {
     *     System.out.println("HTTP服务端口(80)开放");
     * } else {
     *     System.out.println("HTTP服务端口(80)关闭");
     * }
     * 
     * // 检测数据库端口
     * if (NetworkUtils.isPortOpen("database.example.com", 3306)) {
     *     System.out.println("MySQL数据库端口(3306)开放");
     * } else {
     *     System.out.println("MySQL数据库端口(3306)关闭");
     * }
     * 
     * // 检测本地服务
     * if (NetworkUtils.isPortOpen("localhost", 8080)) {
     *     System.out.println("本地Web服务(8080)正在运行");
     * } else {
     *     System.out.println("本地Web服务(8080)未运行");
     * }
     * 
     * // 批量检测多个端口
     * int[] ports = {80, 443, 22, 3306, 8080};
     * for (int port : ports) {
     *     boolean isOpen = NetworkUtils.isPortOpen("server.example.com", port);
     *     System.out.printf("端口 %d: %s%n", port, isOpen ? "开放" : "关闭");
     * }
     * 
     * 相关文档：
     * - TCP协议: https://tools.ietf.org/html/rfc793
     * - 端口分配: https://tools.ietf.org/html/rfc6335
     * - Socket编程: https://docs.oracle.com/javase/8/docs/api/java/net/Socket.html
     * 
     * @param host 目标主机地址，可以是IP地址或域名
     * @param port 要检测的端口号，范围0-65535
     * @return true表示端口开放，false表示端口关闭
     */
    public static boolean isPortOpen(String host, int port) {
        return isPortOpen(host, port, 3000);
    }

    /**
     * 检测端口是否开放（指定超时时间）
     * 
     * 超时设置建议：
     * - 本地网络：1000-3000毫秒
     * - 国内网络：3000-5000毫秒
     * - 国际网络：5000-10000毫秒
     * - 慢速网络：10000-30000毫秒
     * 
     * 使用示例：
     * // 快速检测本地端口
     * boolean localPort = NetworkUtils.isPortOpen("localhost", 8080, 1000);
     * 
     * // 检测远程服务器端口
     * boolean remotePort = NetworkUtils.isPortOpen("server.example.com", 22, 10000);
     * 
     * @param host 目标主机地址
     * @param port 要检测的端口号
     * @param timeoutMillis 超时时间（毫秒），建议1000-30000
     * @return true表示端口开放，false表示端口关闭
     */
    public static boolean isPortOpen(String host, int port, int timeoutMillis) {
        try (Socket socket = new Socket()) {
            socket.connect(new InetSocketAddress(host, port), timeoutMillis);
            return true;
        } catch (Exception e) {
            return false;
        }
    }

    /**
     * 检测代理设置
     */
    public static boolean isProxyEnabled() {
        String httpProxy = System.getProperty("http.proxyHost");
        String httpsProxy = System.getProperty("https.proxyHost");
        return (httpProxy != null && !httpProxy.isEmpty()) || 
               (httpsProxy != null && !httpsProxy.isEmpty());
    }

    /**
     * 获取代理信息
     */
    public static String getProxyInfo() {
        String httpProxy = System.getProperty("http.proxyHost");
        String httpPort = System.getProperty("http.proxyPort");
        String httpsProxy = System.getProperty("https.proxyHost");
        String httpsPort = System.getProperty("https.proxyPort");
        
        StringBuilder info = new StringBuilder();
        if (httpProxy != null && !httpProxy.isEmpty()) {
            info.append("HTTP Proxy: ").append(httpProxy);
            if (httpPort != null && !httpPort.isEmpty()) {
                info.append(":").append(httpPort);
            }
            info.append("; ");
        }
        
        if (httpsProxy != null && !httpsProxy.isEmpty()) {
            info.append("HTTPS Proxy: ").append(httpsProxy);
            if (httpsPort != null && !httpsPort.isEmpty()) {
                info.append(":").append(httpsPort);
            }
        }
        
        return info.toString().isEmpty() ? "No proxy configured" : info.toString();
    }

    /**
     * 检测SSL证书有效性
     */
    public static boolean isSSLCertificateValid(String url) {
        return isSSLCertificateValid(url, 5000);
    }

    /**
     * 检测SSL证书有效性（指定超时时间）
     */
    public static boolean isSSLCertificateValid(String url, int timeoutMillis) {
        try {
            if (!url.startsWith("https://")) {
                url = "https://" + url;
            }
            
            URL testUrl = new URL(url);
            HttpsURLConnection connection = (HttpsURLConnection) testUrl.openConnection();
            connection.setConnectTimeout(timeoutMillis);
            connection.setReadTimeout(timeoutMillis);
            connection.setRequestMethod("HEAD");
            
            // 获取证书
            connection.connect();
            Certificate[] certificates = connection.getServerCertificates();
            connection.disconnect();
            
            return certificates != null && certificates.length > 0;
        } catch (Exception e) {
            return false;
        }
    }

    /**
     * 网络速度测试（简单ping测试）
     */
    public static long pingLatency(String host) {
        return pingLatency(host, 3000);
    }

    /**
     * 网络速度测试（简单ping测试，指定超时时间）
     */
    public static long pingLatency(String host, int timeoutMillis) {
        long startTime = System.currentTimeMillis();
        try {
            InetAddress address = InetAddress.getByName(host);
            if (address.isReachable(timeoutMillis)) {
                return System.currentTimeMillis() - startTime;
            }
        } catch (Exception e) {
            // 忽略异常
        }
        return -1; // 表示无法连接
    }

    /**
     * 网络速度测试（多次ping取平均值）
     */
    public static double getAveragePingLatency(String host, int count) {
        return getAveragePingLatency(host, count, 3000);
    }

    /**
     * 网络速度测试（多次ping取平均值，指定超时时间）
     */
    public static double getAveragePingLatency(String host, int count, int timeoutMillis) {
        long totalLatency = 0;
        int successCount = 0;
        
        for (int i = 0; i < count; i++) {
            long latency = pingLatency(host, timeoutMillis);
            if (latency >= 0) {
                totalLatency += latency;
                successCount++;
            }
        }
        
        return successCount > 0 ? (double) totalLatency / successCount : -1;
    }

    /**
     * 验证IPv4地址格式
     */
    public static boolean isValidIPv4Address(String ip) {
        if (ip == null) {
            return false;
        }
        String[] parts = ip.split("\\.");
        if (parts.length != 4) {
            return false;
        }
        
        for (String part : parts) {
            try {
                int num = Integer.parseInt(part);
                if (num < 0 || num > 255) {
                    return false;
                }
            } catch (NumberFormatException e) {
                return false;
            }
        }
        return true;
    }

    /**
     * 验证IPv6地址
     */
    public static boolean isValidIPv6Address(String ip) {
        if (ip == null) {
            return false;
        }
        return IPV6_PATTERN.matcher(ip).matches();
    }

    /**
     * 统一验证IP地址（支持IPv4和IPv6）
     */
    public static boolean isValidIPAddress(String ip) {
        return isValidIPv4Address(ip) || isValidIPv6Address(ip);
    }

    /**
     * 验证域名格式
     */
    public static boolean isValidDomain(String domain) {
        if (domain == null || domain.isEmpty()) {
            return false;
        }
        return DOMAIN_PATTERN.matcher(domain).matches();
    }

    /**
     * 验证URL格式
     */
    public static boolean isValidURL(String url) {
        try {
            new URL(url);
            return true;
        } catch (Exception e) {
            return false;
        }
    }

    /**
     * 获取URL的域名部分
     */
    public static String extractDomain(String url) {
        try {
            URL parsedUrl = new URL(url.startsWith("http") ? url : "http://" + url);
            return parsedUrl.getHost();
        } catch (Exception e) {
            return null;
        }
    }

    /**
     * 获取URL的协议部分
     */
    public static String extractProtocol(String url) {
        try {
            URL parsedUrl = new URL(url.startsWith("http") ? url : "http://" + url);
            return parsedUrl.getProtocol();
        } catch (Exception e) {
            return "http";
        }
    }

    /**
     * 检测指定的IPv4地址是否为内网地址。
     * 
     * <p>内网地址范围定义：</p>
     * <ul>
     *   <li><strong>10.0.0.0/8</strong> - 10.0.0.0 到 10.255.255.255</li>
     *   <li><strong>172.16.0.0/12</strong> - 172.16.0.0 到 172.31.255.255</li>
     *   <li><strong>192.168.0.0/16</strong> - 192.168.0.0 到 192.168.255.255</li>
     *   <li><strong>127.0.0.0/8</strong> - 127.0.0.0 到 127.255.255.255（回环地址）</li>
     * </ul>
     * 
     * <p>检测原理：</p>
     * <ol>
     *   <li>首先验证IPv4地址格式的有效性</li>
     *   <li>解析地址的四个八位字节</li>
     *   <li>根据RFC 1918标准判断地址范围</li>
     *   <li>返回布尔值表示是否为内网地址</li>
     * </ol>
     * 
     * <p>使用场景：</p>
     * <ul>
     *   <li>网络安全策略实施</li>
     *   <li>网络配置验证</li>
     *   <li>防火墙规则配置</li>
     *   <li>网络拓扑分析</li>
     *   <li>应用程序安全控制</li>
     * </ul>
     * 
     * <p>使用示例：</p>
     * <pre>{@code
     * // 检测内网地址
     * boolean isPrivate1 = NetworkUtils.isPrivateIPv4Address("192.168.1.1");
     * System.out.println("192.168.1.1 是内网地址: " + isPrivate1); // true
     * 
     * // 检测公网地址
     * boolean isPrivate2 = NetworkUtils.isPrivateIPv4Address("8.8.8.8");
     * System.out.println("8.8.8.8 是内网地址: " + isPrivate2); // false
     * 
     * // 检测回环地址
     * boolean isPrivate3 = NetworkUtils.isPrivateIPv4Address("127.0.0.1");
     * System.out.println("127.0.0.1 是内网地址: " + isPrivate3); // true
     * 
     * // 批量检测IP地址
     * String[] testIPs = {"10.0.0.1", "172.16.0.1", "192.168.1.1", "8.8.8.8"};
     * for (String ip : testIPs) {
     *     if (isPrivateIPv4Address(ip)) {
     *         System.out.println(ip + " 是内网地址");
     *     } else {
     *         System.out.println(ip + " 是公网地址");
     *     }
     * }
     * }</pre>
     * 
     * <p>相关标准：</p>
     * <ul>
     *   <li><a href="https://tools.ietf.org/html/rfc1918">RFC 1918</a> - 私有网络地址分配</li>
     *   <li><a href="https://tools.ietf.org/html/rfc5735">RFC 5735</a> - 特殊用途IPv4地址</li>
     *   <li><a href="https://tools.ietf.org/html/rfc6890">RFC 6890</a> - 特殊用途地址注册表</li>
     * </ul>
     * 
     * <p>注意事项：</p>
     * <ul>
     *   <li>此方法仅适用于IPv4地址，IPv6地址请使用 {@link #isPrivateIPv6Address(String)}</li>
     *   <li>回环地址（127.0.0.0/8）也被认为是内网地址</li>
     *   <li>某些特殊用途地址可能不在标准内网范围内</li>
     *   <li>建议在网络安全策略中结合其他验证方法使用</li>
     * </ul>
     * 
     * @param ip 要检测的IPv4地址，不能为null或空字符串
     * @return {@code true} 表示是内网地址，{@code false} 表示是公网地址
     * @throws IllegalArgumentException 如果IPv4地址格式无效
     * @see #isPrivateIPv6Address(String)
     * @see #isPrivateIPAddress(String)
     * @see #isValidIPv4Address(String)
     * @see #isPublicIPAddress(String)
     * @since 1.0
     */
    public static boolean isPrivateIPv4Address(String ip) {
        if (!isValidIPv4Address(ip)) {
            return false;
        }
        
        String[] parts = ip.split("\\.");
        int first = Integer.parseInt(parts[0]);
        int second = Integer.parseInt(parts[1]);
        
        // 10.0.0.0 - 10.255.255.255
        if (first == 10) {
            return true;
        }
        
        // 172.16.0.0 - 172.31.255.255
        if (first == 172 && second >= 16 && second <= 31) {
            return true;
        }
        
        // 192.168.0.0 - 192.168.255.255
        if (first == 192 && second == 168) {
            return true;
        }
        
        // 127.0.0.0 - 127.255.255.255 (回环地址)
        if (first == 127) {
            return true;
        }
        
        return false;
    }

    /**
     * 检测IPv4地址是否属于大型内网地址段（10.0.0.0/8）
     *
     * <p>大型内网地址段特点：</p>
     * <ul>
     *   <li><strong>地址范围</strong>：10.0.0.0 - 10.255.255.255</li>
     *   <li><strong>子网掩码</strong>：255.0.0.0 (/8)</li>
     *   <li><strong>可用地址数量</strong>：16,777,214个（约1677万个）</li>
     *   <li><strong>适用场景</strong>：大型企业、数据中心、云服务提供商、政府机构</li>
     * </ul>
     *
     * <p>检测原理：</p>
     * <ul>
     *   <li>验证IPv4地址格式有效性</li>
     *   <li>检查第一个八位字节是否为10</li>
     *   <li>其他三个八位字节可以是任意值（0-255）</li>
     * </ul>
     *
     * <p>使用示例：</p>
     * <pre>{@code
     * // 检测大型内网地址
     * boolean isLargeNetwork1 = NetworkUtils.isLargePrivateNetworkIPv4Address("10.0.0.1");
     * System.out.println("10.0.0.1 是大型内网地址: " + isLargeNetwork1); // true
     *
     * boolean isLargeNetwork2 = NetworkUtils.isLargePrivateNetworkIPv4Address("10.255.255.254");
     * System.out.println("10.255.255.254 是大型内网地址: " + isLargeNetwork2); // true
     *
     * boolean isLargeNetwork3 = NetworkUtils.isLargePrivateNetworkIPv4Address("11.0.0.1");
     * System.out.println("11.0.0.1 是大型内网地址: " + isLargeNetwork3); // false
     * }</pre>
     *
     * @param ip 要检测的IPv4地址
     * @return {@code true} 表示属于大型内网地址段，{@code false} 表示不属于
     * @see #isMediumPrivateNetworkIPv4Address(String)
     * @see #isSmallPrivateNetworkIPv4Address(String)
     * @see #isIPv4LoopbackAddress(String)
     * @since 1.0
     */
    public static boolean isLargePrivateNetworkIPv4Address(String ip) {
        if (!isValidIPv4Address(ip)) {
            return false;
        }

        String[] parts = ip.split("\\.");
        int firstOctet = Integer.parseInt(parts[0]);

        // 10.0.0.0 - 10.255.255.255
        return firstOctet == 10;
    }

    /**
     * 检测IPv4地址是否属于中型内网地址段（172.16.0.0/12）
     *
     * <p>中型内网地址段特点：</p>
     * <ul>
     *   <li><strong>地址范围</strong>：172.16.0.0 - 172.31.255.255</li>
     *   <li><strong>子网掩码</strong>：255.240.0.0 (/12)</li>
     *   <li><strong>可用地址数量</strong>：1,048,576个（约104万个）</li>
     *   <li><strong>适用场景</strong>：中型企业、多分支机构、网络服务提供商、教育机构</li>
     * </ul>
     *
     * <p>检测原理：</p>
     * <ul>
     *   <li>验证IPv4地址格式有效性</li>
     *   <li>检查第一个八位字节是否为172</li>
     *   <li>检查第二个八位字节是否在16-31范围内</li>
     *   <li>其他两个八位字节可以是任意值（0-255）</li>
     * </ul>
     *
     * <p>使用示例：</p>
     * <pre>{@code
     * // 检测中型内网地址
     * boolean isMediumNetwork1 = NetworkUtils.isMediumPrivateNetworkIPv4Address("172.16.0.1");
     * System.out.println("172.16.0.1 是中型内网地址: " + isMediumNetwork1); // true
     *
     * boolean isMediumNetwork2 = NetworkUtils.isMediumPrivateNetworkIPv4Address("172.31.255.254");
     * System.out.println("172.31.255.254 是中型内网地址: " + isMediumNetwork2); // true
     *
     * boolean isMediumNetwork3 = NetworkUtils.isMediumPrivateNetworkIPv4Address("172.15.0.1");
     * System.out.println("172.15.0.1 是中型内网地址: " + isMediumNetwork3); // false
     *
     * boolean isMediumNetwork4 = NetworkUtils.isMediumPrivateNetworkIPv4Address("172.32.0.1");
     * System.out.println("172.32.0.1 是中型内网地址: " + isMediumNetwork4); // false
     * }</pre>
     *
     * @param ip 要检测的IPv4地址
     * @return {@code true} 表示属于中型内网地址段，{@code false} 表示不属于
     * @see #isLargePrivateNetworkIPv4Address(String)
     * @see #isSmallPrivateNetworkIPv4Address(String)
     * @see #isIPv4LoopbackAddress(String)
     * @since 1.0
     */
    public static boolean isMediumPrivateNetworkIPv4Address(String ip) {
        if (!isValidIPv4Address(ip)) {
            return false;
        }

        String[] parts = ip.split("\\.");
        int firstOctet = Integer.parseInt(parts[0]);
        int secondOctet = Integer.parseInt(parts[1]);

        // 172.16.0.0 - 172.31.255.255
        return firstOctet == 172 && secondOctet >= 16 && secondOctet <= 31;
    }

    /**
     * 检测IPv4地址是否属于小型内网地址段（192.168.0.0/16）
     *
     * <p>小型内网地址段特点：</p>
     * <ul>
     *   <li><strong>地址范围</strong>：192.168.0.0 - 192.168.255.255</li>
     *   <li><strong>子网掩码</strong>：255.255.0.0 (/16)</li>
     *   <li><strong>可用地址数量</strong>：65,536个（约6.5万个）</li>
     *   <li><strong>适用场景</strong>：家庭网络、小型办公室、路由器默认配置、个人开发环境</li>
     * </ul>
     *
     * <p>检测原理：</p>
     * <ul>
     *   <li>验证IPv4地址格式有效性</li>
     *   <li>检查第一个八位字节是否为192</li>
     *   <li>检查第二个八位字节是否为168</li>
     *   <li>其他两个八位字节可以是任意值（0-255）</li>
     * </ul>
     *
     * <p>使用示例：</p>
     * <pre>{@code
     * // 检测小型内网地址
     * boolean isSmallNetwork1 = NetworkUtils.isSmallPrivateNetworkIPv4Address("192.168.1.1");
     * System.out.println("192.168.1.1 是小型内网地址: " + isSmallNetwork1); // true
     *
     * boolean isSmallNetwork2 = NetworkUtils.isSmallPrivateNetworkIPv4Address("192.168.255.254");
     * System.out.println("192.168.255.254 是小型内网地址: " + isSmallNetwork2); // true
     *
     * boolean isSmallNetwork3 = NetworkUtils.isSmallPrivateNetworkIPv4Address("192.169.0.1");
     * System.out.println("192.169.0.1 是小型内网地址: " + isSmallNetwork3); // false
     *
     * boolean isSmallNetwork4 = NetworkUtils.isSmallPrivateNetworkIPv4Address("193.168.0.1");
     * System.out.println("193.168.0.1 是小型内网地址: " + isSmallNetwork4); // false
     * }</pre>
     *
     * @param ip 要检测的IPv4地址
     * @return {@code true} 表示属于小型内网地址段，{@code false} 表示不属于
     * @see #isLargePrivateNetworkIPv4Address(String)
     * @see #isMediumPrivateNetworkIPv4Address(String)
     * @see #isIPv4LoopbackAddress(String)
     * @since 1.0
     */
    public static boolean isSmallPrivateNetworkIPv4Address(String ip) {
        if (!isValidIPv4Address(ip)) {
            return false;
        }

        String[] parts = ip.split("\\.");
        int firstOctet = Integer.parseInt(parts[0]);
        int secondOctet = Integer.parseInt(parts[1]);

        // 192.168.0.0 - 192.168.255.255
        return firstOctet == 192 && secondOctet == 168;
    }


    /**
     * 检测是否为公网IP地址
     */
    public static boolean isPublicIPAddress(String ip) {
        return isValidIPAddress(ip) && !isPrivateIPAddress(ip) && !LOCAL_LOOPBACK_V4_IP.equals(ip);
    }

    /**
     * 获取网络连接质量评级
     */
    public static String getNetworkQualityRating(String host) {
        double avgLatency = getAveragePingLatency(host, 3);
        
        if (avgLatency < 0) {
            return "UNREACHABLE";
        } else if (avgLatency < 50) {
            return "EXCELLENT";
        } else if (avgLatency < 100) {
            return "GOOD";
        } else if (avgLatency < 200) {
            return "FAIR";
        } else {
            return "POOR";
        }
    }

    /**
     * 批量检测多个主机的连通性
     */
    public static java.util.Map<String, Boolean> batchCheckConnectivity(String... hosts) {
        java.util.Map<String, Boolean> results = new java.util.HashMap<>();
        
        for (String host : hosts) {
            results.put(host, isWebsiteAccessible(host));
        }
        
        return results;
    }

    /**
     * 异步批量检测多个主机的连通性
     */
    public static CompletableFuture<java.util.Map<String, Boolean>> batchCheckConnectivityAsync(String... hosts) {
        return CompletableFuture.supplyAsync(() -> batchCheckConnectivity(hosts));
    }

    /**
     * 将IPv4地址转换为长整型数字
     * 
     * @param ip IPv4地址，如 "192.168.1.1"
     * @return 对应的长整型数字，如果转换失败返回-1
     */
    public static long ipv4ToLong(String ip) {
        if (!isValidIPv4Address(ip)) {
            return -1;
        }
        
        try {
            String[] parts = ip.split("\\.");
            long result = 0;
            
            for (int i = 0; i < 4; i++) {
                int part = Integer.parseInt(parts[i]);
                result = (result << 8) | (part & 0xFF);
            }
            
            return result;
        } catch (Exception e) {
            return -1;
        }
    }

    /**
     * 将长整型数字转换为IPv4地址
     * 
     * @param ipLong 长整型数字
     * @return 对应的IPv4地址，如 "192.168.1.1"
     */
    public static String longToIPv4(long ipLong) {
        if (ipLong < 0 || ipLong > 0xFFFFFFFFL) {
            return null;
        }
        
        StringBuilder ip = new StringBuilder();
        
        for (int i = 3; i >= 0; i--) {
            int part = (int) ((ipLong >> (i * 8)) & 0xFF);
            ip.append(part);
            if (i > 0) {
                ip.append(".");
            }
        }
        
        return ip.toString();
    }

    /**
     * 将IPv6地址转换为BigInteger（因为IPv6是128位，超出long范围）
     * 
     * @param ip IPv6地址，如 "2001:db8::1"
     * @return 对应的BigInteger，如果转换失败返回null
     */
    public static java.math.BigInteger ipv6ToBigInteger(String ip) {
        if (!isValidIPv6Address(ip)) {
            return null;
        }
        
        try {
            // 标准化IPv6地址
            InetAddress address = InetAddress.getByName(ip);
            if (!(address instanceof Inet6Address)) {
                return null;
            }
            
            byte[] bytes = address.getAddress();
            return new BigInteger(1, bytes); // 使用1表示正数
        } catch (Exception e) {
            return null;
        }
    }

    /**
     * 将BigInteger转换为IPv6地址
     * 
     * @param bigInt BigInteger数字
     * @return 对应的IPv6地址，如 "2001:db8::1"
     */
    public static String bigIntegerToIPv6(BigInteger bigInt) {
        if (bigInt == null || bigInt.compareTo(java.math.BigInteger.ZERO) < 0) {
            return null;
        }
        
        try {
            byte[] bytes = bigInt.toByteArray();
            
            // 确保字节数组长度为16（IPv6地址长度）
            byte[] ipv6Bytes = new byte[16];
            if (bytes.length > 16) {
                // 如果超过16字节，取最后16字节
                System.arraycopy(bytes, bytes.length - 16, ipv6Bytes, 0, 16);
            } else {
                // 如果少于16字节，在前面补0
                System.arraycopy(bytes, 0, ipv6Bytes, 16 - bytes.length, bytes.length);
            }
            
            InetAddress address = InetAddress.getByAddress(ipv6Bytes);
            return address.getHostAddress();
        } catch (Exception e) {
            return null;
        }
    }

    /**
     * 将IP地址转换为数字（自动识别IPv4/IPv6）
     * 
     * @param ip IP地址
     * @return 转换结果对象，包含数字值和类型信息
     */
    public static IPNumber ipToNumber(String ip) {
        if (isValidIPv4Address(ip)) {
            long longValue = ipv4ToLong(ip);
            return new IPNumber(longValue, null, IPVersion.IPv4);
        } else if (isValidIPv6Address(ip)) {
            BigInteger bigIntValue = ipv6ToBigInteger(ip);
            return new IPNumber(-1, bigIntValue, IPVersion.IPv6);
        }
        throw new IllegalArgumentException("Invalid IP address");
    }

    /**
     * 将数字转换为IP地址
     * 
     * @param number 数字值
     * @param version IP版本
     * @return 对应的IP地址
     */
    public static String numberToIP(Object number, IPVersion version) {
        if (version == IPVersion.IPv4) {
            if (number instanceof Long) {
                return longToIPv4((Long) number);
            } else if (number instanceof Integer) {
                return longToIPv4(((Integer) number).longValue());
            }
        } else if (version == IPVersion.IPv6) {
            if (number instanceof java.math.BigInteger) {
                return bigIntegerToIPv6((java.math.BigInteger) number);
            }
        }
        return null;
    }

    /**
     * 获取IP地址的数字范围（用于CIDR计算）
     * 
     * CIDR（Classless Inter-Domain Routing）概念说明：
     * - CIDR是一种IP地址分配方法，用于更有效地分配IP地址空间
     * - 格式：IP地址/前缀长度，例如：192.168.1.0/24
     * - 前缀长度表示网络部分的位数，决定了网络的大小
     * 
     * 子网掩码位数（前缀长度）说明：
     * - IPv4：0-32位，IPv6：0-128位
     * - 位数越大，网络越小，可用IP地址越少
     * - 位数越小，网络越大，可用IP地址越多
     * 
     * 常见前缀长度示例：
     * - /24 (255.255.255.0)：256个IP地址，常用的小型网络
     * - /16 (255.255.0.0)：65536个IP地址，中型网络
     * - /8 (255.0.0.0)：16777216个IP地址，大型网络
     * - /32 (255.255.255.255)：1个IP地址，单个主机
     * 
     * 使用示例：
     * // 计算192.168.1.0/24网段的IP范围
     * IPRangeResult range = NetworkUtils.getIPRange("192.168.1.0", 24);
     * System.out.println("网段起始IP: " + range.getStartIP());  // 192.168.1.0
     * System.out.println("网段结束IP: " + range.getEndIP());    // 192.168.1.255
     * 
     * // 计算10.0.0.0/8网段的IP范围
     * IPRangeResult largeRange = NetworkUtils.getIPRange("10.0.0.0", 8);
     * System.out.println("大网段起始IP: " + largeRange.getStartIP());  // 10.0.0.0
     * System.out.println("大网段结束IP: " + largeRange.getEndIP());    // 10.255.255.255
     * 
     * // 计算单个IP地址的范围
     * IPRangeResult singleIP = NetworkUtils.getIPRange("192.168.1.100", 32);
     * System.out.println("单个IP: " + singleIP.getStartIP());  // 192.168.1.100
     * 
     * // IPv6示例：计算2001:db8::/64网段
     * IPRangeResult ipv6Range = NetworkUtils.getIPRange("2001:db8::", 64);
     * System.out.println("IPv6网段起始: " + ipv6Range.getStartIP());
     * System.out.println("IPv6网段结束: " + ipv6Range.getEndIP());
     * 
     * @param ip IP地址，如 "192.168.1.0" 或 "2001:db8::"
     * @param prefixLength 前缀长度（子网掩码位数）
     *                    IPv4: 0-32位，IPv6: 0-128位
     *                    常用值：/24(256个IP), /16(65536个IP), /8(16777216个IP)
     * @return 包含起始和结束IP地址的范围对象，如果参数无效返回null
     */
    public static IPRange getIPRange(String ip, int prefixLength) {
        if (isValidIPv4Address(ip)) {
            return getIPv4Range(ip, prefixLength);
        } else if (isValidIPv6Address(ip)) {
            return getIPv6Range(ip, prefixLength);
        }
        return null;
    }

    /**
     * 获取IPv4地址范围（内部方法）
     * 
     * 计算原理：
     * 1. 将IP地址转换为长整型数字
     * 2. 根据前缀长度计算子网掩码
     * 3. 使用掩码计算网络地址（起始IP）
     * 4. 计算广播地址（结束IP）
     * 
     * 例如：192.168.1.0/24
     * - IP地址：192.168.1.0 = 3232235776
     * - 前缀长度：24位
     * - 子网掩码：255.255.255.0 = 4294967040
     * - 网络地址：3232235776 & 4294967040 = 3232235776 (192.168.1.0)
     * - 广播地址：3232235776 | 255 = 3232236031 (192.168.1.255)
     * 
     * @param ip IPv4地址
     * @param prefixLength 前缀长度（0-32）
     * @return IP范围结果
     */
    private static IPRange getIPv4Range(String ip, int prefixLength) {
        if (prefixLength < 0 || prefixLength > 32) {
            return null;
        }
        
        long ipLong = ipv4ToLong(ip);
        if (ipLong == -1) {
            return null;
        }
        
        // 计算子网掩码
        long mask = (0xFFFFFFFFL << (32 - prefixLength)) & 0xFFFFFFFFL;
        
        // 计算网络地址（起始IP）
        long startIP = ipLong & mask;
        
        // 计算广播地址（结束IP）
        long endIP = startIP | ((1L << (32 - prefixLength)) - 1);
        
        return new IPRange(
            longToIPv4(startIP),
            longToIPv4(endIP),
            startIP,
            endIP,
            null,
            null,
            IPVersion.IPv4
        );
    }

    /**
     * 获取IPv6地址范围（内部方法）
     * 
     * 计算原理与IPv4类似，但使用BigInteger处理128位地址：
     * 1. 将IPv6地址转换为BigInteger
     * 2. 根据前缀长度计算子网掩码
     * 3. 计算网络地址和广播地址
     * 
     * 例如：2001:db8::/64
     * - 网络部分：前64位
     * - 主机部分：后64位
     * - 可用地址数量：2^64个
     * 
     * @param ip IPv6地址
     * @param prefixLength 前缀长度（0-128）
     * @return IP范围结果
     */
    private static IPRange getIPv6Range(String ip, int prefixLength) {
        if (prefixLength < 0 || prefixLength > 128) {
            return null;
        }
        
        BigInteger ipBigInt = ipv6ToBigInteger(ip);
        if (ipBigInt == null) {
            return null;
        }
        
        // 计算子网掩码
        BigInteger mask = BigInteger.ONE.shiftLeft(128 - prefixLength).subtract(BigInteger.ONE);
        
        // 计算网络地址（起始IP）
        BigInteger startIP = ipBigInt.and(mask.not());
        
        // 计算广播地址（结束IP）
        BigInteger endIP = startIP.or(mask);
        
        return new IPRange(
            bigIntegerToIPv6(startIP),
            bigIntegerToIPv6(endIP),
            -1,
            -1,
            startIP,
            endIP,
            IPVersion.IPv6
        );
    }

    /**
     * 检测是否为内网IPv6地址
     */
    public static boolean isPrivateIPv6Address(String ip) {
        if (!isValidIPv6Address(ip)) {
            return false;
        }
        
        // 本地链路地址 fe80::/10
        if (ip.toLowerCase().startsWith("fe80:")) {
            return true;
        }
        
        // 唯一本地地址 fc00::/7
        if (ip.toLowerCase().startsWith("fc") || ip.toLowerCase().startsWith("fd")) {
            return true;
        }
        
        // 回环地址 ::1
        if (ip.equals("::1")) {
            return true;
        }
        
        // 未指定地址 ::
        if (ip.equals("::")) {
            return true;
        }
        
        return false;
    }

    /**
     * 统一内网地址检测
     */
    public static boolean isPrivateIPAddress(String ip) {
        return isPrivateIPv4Address(ip) || isPrivateIPv6Address(ip);
    }

    /**
     * 检测系统是否支持IPv6
     */
    public static boolean isIPv6Supported() {
        try {
            Enumeration<NetworkInterface> interfaces = NetworkInterface.getNetworkInterfaces();
            while (interfaces.hasMoreElements()) {
                NetworkInterface networkInterface = interfaces.nextElement();
                if (networkInterface.isUp()) {
                    Enumeration<InetAddress> addresses = networkInterface.getInetAddresses();
                    while (addresses.hasMoreElements()) {
                        InetAddress address = addresses.nextElement();
                        if (address instanceof Inet6Address) {
                            return true;
                        }
                    }
                }
            }
        } catch (Exception e) {
            // 忽略异常
        }
        return false;
    }

    /**
     * 检测系统是否支持IPv4
     */
    public static boolean isIPv4Supported() {
        try {
            Enumeration<NetworkInterface> interfaces = NetworkInterface.getNetworkInterfaces();
            while (interfaces.hasMoreElements()) {
                NetworkInterface networkInterface = interfaces.nextElement();
                if (networkInterface.isUp()) {
                    Enumeration<InetAddress> addresses = networkInterface.getInetAddresses();
                    while (addresses.hasMoreElements()) {
                        InetAddress address = addresses.nextElement();
                        if (address instanceof Inet4Address) {
                            return true;
                        }
                    }
                }
            }
        } catch (Exception e) {
            // 忽略异常
        }
        return false;
    }


    /**
     * 检测是否为IPv4映射的IPv6地址
     */
    public static boolean isIPv4MappedIPv6Address(String ip) {
        if (!isValidIPv6Address(ip)) {
            return false;
        }
        return ip.toLowerCase().startsWith("::ffff:");
    }

    /**
     * 从IPv4映射的IPv6地址中提取IPv4地址
     */
    public static String extractIPv4FromMappedIPv6(String ip) {
        if (!isIPv4MappedIPv6Address(ip)) {
            return null;
        }
        
        try {
            String ipv4Part = ip.substring(7);
            if (isValidIPv4Address(ipv4Part)) {
                return ipv4Part;
            }
        } catch (Exception e) {
            // 忽略异常
        }
        return null;
    }

    /**
     * 获取IP地址版本
     */
    public static IPVersion getIPVersion(String ip) {
        if (isValidIPv4Address(ip)) {
            return IPVersion.IPv4;
        } else if (isValidIPv6Address(ip)) {
            return IPVersion.IPv6;
        }
        return IPVersion.UNKNOWN;
    }

    /**
     * 获取本机所有网络接口（网卡）信息
     * 
     * 网卡信息获取原理：
     * - 使用NetworkInterface.getNetworkInterfaces()获取系统所有网络接口
     * - 返回包含所有网络接口的列表，无论是否启用
     * - 包括物理网卡、虚拟网卡、回环接口等
     * 
     * 返回的网络接口类型说明：
     * - 物理网卡：真实的网络硬件设备，如以太网卡、无线网卡
     * - 虚拟网卡：软件创建的虚拟网络接口，如VPN、虚拟机网卡
     * - 回环接口：用于本机通信的虚拟接口，如127.0.0.1
     * - 隧道接口：网络隧道协议创建的接口，如IPv6隧道
     * - 桥接接口：网络桥接功能创建的接口
     * 
     * 网络接口状态说明：
     * - isUp()：接口是否启用
     * - isLoopback()：是否为回环接口
     * - isVirtual()：是否为虚拟接口
     * - isPointToPoint()：是否为点对点接口
     * - isMulticastSupported()：是否支持多播
     * 
     * 使用场景：
     * - 网络配置管理和监控
     * - 网络接口状态检查
     * - 网络故障诊断
     * - 网络性能分析
     * - 系统网络信息收集
     * 
     * 使用示例：
     * // 获取所有网卡信息
     * List<NetworkInterface> allInterfaces = NetworkUtils.getAllNetworkInterfaces();
     * 
     * // 遍历并显示网卡信息
     * for (NetworkInterface networkInterface : allInterfaces) {
     *     System.out.println("网卡名称: " + networkInterface.getDisplayName());
     *     System.out.println("网卡索引: " + networkInterface.getIndex());
     *     System.out.println("是否启用: " + networkInterface.isUp());
     *     System.out.println("是否回环: " + networkInterface.isLoopback());
     *     System.out.println("是否虚拟: " + networkInterface.isVirtual());
     *     System.out.println("MTU: " + networkInterface.getMTU());
     *     
     *     // 获取IP地址
     *     Enumeration<InetAddress> addresses = networkInterface.getInetAddresses();
     *     while (addresses.hasMoreElements()) {
     *         InetAddress address = addresses.nextElement();
     *         System.out.println("  IP地址: " + address.getHostAddress());
     *     }
     *     System.out.println("------------------------");
     * }
     * 
     * // 筛选启用的网卡
     * List<NetworkInterface> activeInterfaces = allInterfaces.stream()
     *     .filter(NetworkInterface::isUp)
     *     .collect(Collectors.toList());
     * 
     * // 筛选物理网卡（非虚拟）
     * List<NetworkInterface> physicalInterfaces = allInterfaces.stream()
     *     .filter(iface -> !iface.isVirtual())
     *     .collect(Collectors.toList());
     * 
     * // 筛选支持多播的网卡
     * List<NetworkInterface> multicastInterfaces = allInterfaces.stream()
     *     .filter(NetworkInterface::isMulticastSupported)
     *     .collect(Collectors.toList());
     * 
     * // 获取特定名称的网卡
     * Optional<NetworkInterface> eth0 = allInterfaces.stream()
     *     .filter(iface -> "eth0".equals(iface.getName()))
     *     .findFirst();
     * 
     * // 统计网卡数量
     * long totalCount = allInterfaces.size();
     * long activeCount = allInterfaces.stream().filter(NetworkInterface::isUp).count();
     * long virtualCount = allInterfaces.stream().filter(NetworkInterface::isVirtual).count();
     * 
     * System.out.println("总网卡数: " + totalCount);
     * System.out.println("启用网卡数: " + activeCount);
     * System.out.println("虚拟网卡数: " + virtualCount);
     * 
     * 相关文档：
     * - NetworkInterface: https://docs.oracle.com/javase/8/docs/api/java/net/NetworkInterface.html
     * - InetAddress: https://docs.oracle.com/javase/8/docs/api/java/net/InetAddress.html
     * - 网络接口管理: https://docs.oracle.com/javase/8/docs/api/java/net/NetworkInterface.html#getNetworkInterfaces()
     * 
     * @return 包含所有网络接口的列表，如果没有找到任何接口则返回空列表
     * @throws SecurityException 如果没有足够的权限访问网络接口信息
     * @throws NetworkException 如果获取网络接口信息时发生I/O错误
     */
    public static List<NetworkInterface> getAllNetworkInterfaces() {
        List<NetworkInterface> interfaceList = new ArrayList<>();
        Enumeration<NetworkInterface> networkInterfaces;
        try {
            networkInterfaces = NetworkInterface.getNetworkInterfaces();
        } catch (SocketException e) {
            throw new NetworkException(e);
        }
        while (networkInterfaces.hasMoreElements()) {
            NetworkInterface networkInterface = networkInterfaces.nextElement();
            interfaceList.add(networkInterface);
        }
        
        return interfaceList;
    }

    /**
     * 获取本机所有启用的网络接口（网卡）信息
     * 
     * 启用网卡筛选原理：
     * - 调用getAllNetworkInterfaces()获取所有网络接口
     * - 使用isUp()方法筛选出状态为启用的接口
     * - 排除已禁用或故障的网络接口
     * 
     * 启用状态说明：
     * - isUp()返回true：网卡已启用且正常工作
     * - isUp()返回false：网卡已禁用或存在故障
     * 
     * 使用场景：
     * - 获取当前可用的网络连接
     * - 网络状态监控
     * - 网络配置验证
     * - 网络故障排除
     * 
     * 使用示例：
     * // 获取所有启用的网卡
     * List<NetworkInterface> activeInterfaces = NetworkUtils.getActiveNetworkInterfaces();
     * 
     * // 显示启用网卡的信息
     * for (NetworkInterface networkInterface : activeInterfaces) {
     *     System.out.println("启用网卡: " + networkInterface.getDisplayName());
     *     System.out.println("接口名称: " + networkInterface.getName());
     *     System.out.println("MTU: " + networkInterface.getMTU());
     * }
     * 
     * @return 包含所有启用网络接口的列表，如果没有启用的接口则返回空列表
     * @throws SecurityException 如果没有足够的权限访问网络接口信息
     * @throws NetworkException 如果获取网络接口信息时发生I/O错误
     */
    public static List<NetworkInterface> getActiveNetworkInterfaces() {
        List<NetworkInterface> activeInterfaces = new ArrayList<>();
        try {
            for (NetworkInterface networkInterface : getAllNetworkInterfaces()) {
                if (networkInterface.isUp()) {
                    activeInterfaces.add(networkInterface);
                }
            }
        } catch (SocketException e) {
            throw new NetworkException(e);
        }

        return activeInterfaces;
    }

    /**
     * 获取本机所有物理网络接口（网卡）信息
     * 
     * 物理网卡筛选原理：
     * - 调用getAllNetworkInterfaces()获取所有网络接口
     * - 使用isVirtual()方法筛选出非虚拟的接口
     * - 排除VPN、虚拟机、隧道等虚拟网络接口
     * 
     * 物理网卡特征：
     * - isVirtual()返回false：真实的网络硬件设备
     * - 通常具有固定的硬件地址（MAC地址）
     * - 支持硬件级别的网络功能
     * 
     * 使用场景：
     * - 硬件网络设备管理
     * - 网络性能优化
     * - 硬件故障诊断
     * - 网络拓扑分析
     * 
     * 使用示例：
     * // 获取所有物理网卡
     * List<NetworkInterface> physicalInterfaces = NetworkUtils.getPhysicalNetworkInterfaces();
     * 
     * // 显示物理网卡信息
     * for (NetworkInterface networkInterface : physicalInterfaces) {
     *     System.out.println("物理网卡: " + networkInterface.getDisplayName());
     *     
     *     // 获取硬件地址（MAC地址）
     *     byte[] mac = networkInterface.getHardwareAddress();
     *     if (mac != null) {
     *         StringBuilder sb = new StringBuilder();
     *         for (int i = 0; i < mac.length; i++) {
     *             sb.append(String.format("%02X%s", mac[i], (i < mac.length - 1) ? "-" : ""));
     *         }
     *         System.out.println("MAC地址: " + sb.toString());
     *     }
     * }
     * 
     * @return 包含所有物理网络接口的列表，如果没有物理接口则返回空列表
     * @throws SecurityException 如果没有足够的权限访问网络接口信息
     * @throws NetworkException 如果获取网络接口信息时发生I/O错误
     */
    public static List<NetworkInterface> getPhysicalNetworkInterfaces() {
        List<NetworkInterface> physicalInterfaces = new ArrayList<>();
        for (NetworkInterface networkInterface : getAllNetworkInterfaces()) {
            if (!networkInterface.isVirtual()) {
                physicalInterfaces.add(networkInterface);
            }
        }
        return physicalInterfaces;
    }

    /**
     * 获取本机所有虚拟网络接口（网卡）信息
     * 
     * 虚拟网卡筛选原理：
     * - 调用getAllNetworkInterfaces()获取所有网络接口
     * - 使用isVirtual()方法筛选出虚拟的接口
     * - 包括VPN、虚拟机、隧道、桥接等软件创建的虚拟接口
     * 
     * 虚拟网卡类型说明：
     * - VPN接口：虚拟专用网络接口，如OpenVPN、WireGuard等
     * - 虚拟机接口：虚拟机软件创建的网络接口，如VMware、VirtualBox等
     * - 隧道接口：网络隧道协议创建的接口，如IPv6隧道、GRE隧道等
     * - 桥接接口：网络桥接功能创建的虚拟接口
     * - 回环接口：用于本机通信的虚拟接口，如127.0.0.1
     * - 容器接口：Docker、Kubernetes等容器技术创建的网络接口
     * - 软件定义网络接口：SDN控制器创建的虚拟网络接口
     * 
     * 虚拟网卡特征：
     * - isVirtual()返回true：软件创建的虚拟网络接口
     * - 通常没有固定的硬件地址（MAC地址可能动态生成）
     * - 支持高级网络功能，如网络隔离、流量控制等
     * - 可以动态创建和销毁
     * - 通常用于网络虚拟化和网络功能虚拟化
     * 
     * 使用场景：
     * - 虚拟网络环境管理
     * - VPN连接状态监控
     * - 虚拟机网络配置
     * - 容器网络管理
     * - 网络虚拟化部署
     * - 网络安全策略实施
     * - 网络流量分析和监控
     * 
     * 使用示例：
     * // 获取所有虚拟网卡
     * List<NetworkInterface> virtualInterfaces = NetworkUtils.getVirtualNetworkInterfaces();
     * 
     * // 显示虚拟网卡信息
     * for (NetworkInterface networkInterface : virtualInterfaces) {
     *     System.out.println("虚拟网卡: " + networkInterface.getDisplayName());
     *     System.out.println("接口名称: " + networkInterface.getName());
     *     System.out.println("是否启用: " + networkInterface.isUp());
     *     System.out.println("是否回环: " + networkInterface.isLoopback());
     *     System.out.println("MTU: " + networkInterface.getMTU());
     *     
     *     // 获取IP地址
     *     Enumeration<InetAddress> addresses = networkInterface.getInetAddresses();
     *     while (addresses.hasMoreElements()) {
     *         InetAddress address = addresses.nextElement();
     *         System.out.println("  IP地址: " + address.getHostAddress());
     *     }
     *     
     *     // 获取硬件地址（可能为null）
     *     byte[] mac = networkInterface.getHardwareAddress();
     *     if (mac != null) {
     *         StringBuilder sb = new StringBuilder();
     *         for (int i = 0; i < mac.length; i++) {
     *             sb.append(String.format("%02X%s", mac[i], (i < mac.length - 1) ? "-" : ""));
     *         }
     *         System.out.println("MAC地址: " + sb.toString());
     *     } else {
     *         System.out.println("MAC地址: 动态生成或无MAC地址");
     *     }
     *     System.out.println("------------------------");
     * }
     * 
     * // 筛选启用的虚拟网卡
     * List<NetworkInterface> activeVirtualInterfaces = virtualInterfaces.stream()
     *     .filter(iface -> {
     *         try {
     *             return iface.isUp();
     *         } catch (SocketException e) {
     *             return false;
     *         }
     *     })
     *     .collect(java.util.stream.Collectors.toList());
     * 
     * // 筛选VPN相关接口
     * List<NetworkInterface> vpnInterfaces = virtualInterfaces.stream()
     *     .filter(iface -> {
     *         String name = iface.getName().toLowerCase();
     *         return name.contains("tun") || name.contains("tap") || 
     *                name.contains("vpn") || name.contains("wireguard");
     *     })
     *     .collect(java.util.stream.Collectors.toList());
     * 
     * // 筛选虚拟机相关接口
     * List<NetworkInterface> vmInterfaces = virtualInterfaces.stream()
     *     .filter(iface -> {
     *         String name = iface.getName().toLowerCase();
     *         return name.contains("vmnet") || name.contains("vbox") || 
     *                name.contains("virbr") || name.contains("docker");
     *     })
     *     .collect(java.util.stream.Collectors.toList());
     * 
     * // 统计虚拟网卡信息
     * long totalVirtualCount = virtualInterfaces.size();
     * long activeVirtualCount = activeVirtualInterfaces.size();
     * long vpnCount = vpnInterfaces.size();
     * long vmCount = vmInterfaces.size();
     * 
     * System.out.println("虚拟网卡总数: " + totalVirtualCount);
     * System.out.println("启用虚拟网卡数: " + activeVirtualCount);
     * System.out.println("VPN接口数: " + vpnCount);
     * System.out.println("虚拟机接口数: " + vmCount);
     * 
     * // 检查特定类型的虚拟网卡
     * boolean hasVPN = !vpnInterfaces.isEmpty();
     * boolean hasVM = !vmInterfaces.isEmpty();
     * 
     * if (hasVPN) {
     *     System.out.println("检测到VPN连接");
     * }
     * if (hasVM) {
     *     System.out.println("检测到虚拟机环境");
     * }
     * 
     * 相关文档：
     * - NetworkInterface: https://docs.oracle.com/javase/8/docs/api/java/net/NetworkInterface.html
     * - 虚拟网络接口: https://docs.oracle.com/javase/8/docs/api/java/net/NetworkInterface.html#isVirtual()
     * - VPN技术: https://tools.ietf.org/html/rfc2764
     * - 网络虚拟化: https://tools.ietf.org/html/rfc7365
     * 
     * @return 包含所有虚拟网络接口的列表，如果没有虚拟接口则返回空列表
     * @throws SecurityException 如果没有足够的权限访问网络接口信息
     * @throws NetworkException 如果获取网络接口信息时发生I/O错误
     */
    public static List<NetworkInterface> getVirtualNetworkInterfaces() {
        List<NetworkInterface> virtualInterfaces = new ArrayList<>();
        for (NetworkInterface networkInterface : getAllNetworkInterfaces()) {
            if (networkInterface.isVirtual()) {
                virtualInterfaces.add(networkInterface);
            }
        }
        return virtualInterfaces;
    }

    /**
     * 通用网卡过滤工具方法
     * 
     * 网卡过滤原理：
     * - 接收一个网卡列表作为输入源
     * - 接收一个过滤条件函数（Predicate<NetworkInterface>）
     * - 使用Stream API进行过滤操作
     * - 返回过滤后的网卡列表
     * 
     * @param networkInterfaces 要过滤的网卡列表，不能为null
     * @param filter 过滤条件函数，不能为null，返回true表示保留该网卡，false表示过滤掉
     * @return 过滤后的网卡列表，如果输入列表为空或所有网卡都被过滤掉则返回空列表
     * @throws IllegalArgumentException 如果输入参数为null
     */
    public static List<NetworkInterface> filterNetworkInterfaces(
            List<NetworkInterface> networkInterfaces,
            Predicate<NetworkInterface> filter) {

        Assert.notEmpty(networkInterfaces , "network interfaces must not be empty");
        Assert.notNull(filter , "filter function must not be null");
        return networkInterfaces.stream()
                .filter(filter)
                .collect(java.util.stream.Collectors.toList());
    }

    /**
     * 通用网卡过滤工具方法（支持多个过滤条件）
     * 
     * @param networkInterfaces 要过滤的网卡列表，不能为null
     * @param filters 过滤条件函数数组，可以为空或null（空时返回原列表）
     * @return 满足所有过滤条件的网卡列表
     * @throws IllegalArgumentException 如果网卡列表为null
     */
    @SafeVarargs
    public static List<NetworkInterface> filterNetworkInterfaces(
            List<NetworkInterface> networkInterfaces,
            final Predicate<NetworkInterface>... filters) {

        Assert.notEmpty(networkInterfaces , "network interfaces must not be empty");

        if (filters == null || filters.length == 0) {
            return new ArrayList<>(networkInterfaces);
        }
        
        return networkInterfaces.stream()
                .filter(iface -> {
                    for (Predicate<NetworkInterface> filter : filters) {
                        if (filter != null && !filter.test(iface)) {
                            return false;
                        }
                    }
                    return true;
                })
                .collect(java.util.stream.Collectors.toList());
    }

    /**
     * 将MAC地址字节数组转换为标准字符串格式
     * 
     * <p>MAC地址说明：</p>
     * <ul>
     *   <li>MAC地址（Media Access Control Address）是网络接口的唯一标识符</li>
     *   <li>标准长度：6字节（48位），表示为12个十六进制字符</li>
     *   <li>十六进制字符：0-9, A-F, a-f</li>
     *   <li>输出格式：XX:XX:XX:XX:XX:XX（冒号分隔）</li>
     * </ul>
     * 
     * <p>转换原理：</p>
     * <ul>
     *   <li>将每个字节转换为两位十六进制数字</li>
     *   <li>使用冒号（:）分隔每个字节</li>
     *   <li>自动处理字节数组长度验证</li>
     *   <li>默认使用大写十六进制输出</li>
     * </ul>
     * 
     * <p>使用场景：</p>
     * <ul>
     *   <li>网卡信息显示和日志记录</li>
     *   <li>MAC地址比较和存储</li>
     *   <li>网络配置管理</li>
     *   <li>网络故障诊断</li>
     * </ul>
     * 
     * <p>使用示例：</p>
     * <pre>{@code
     * // 获取网卡的MAC地址
     * NetworkInterface networkInterface = getAllNetworkInterfaces().get(0);
     * byte[] macBytes = networkInterface.getHardwareAddress();
     * 
     * if (macBytes != null) {
     *     // 转换为标准格式
     *     String macAddress = NetworkUtils.macBytesToString(macBytes);
     *     System.out.println("MAC地址: " + macAddress); // 输出：AA:BB:CC:DD:EE:FF
     * }
     * }</pre>
     * 
     * @param macBytes MAC地址字节数组，必须为6字节长度
     * @return 标准格式的MAC地址字符串，如 "AA:BB:CC:DD:EE:FF"
     * @throws IllegalArgumentException 如果字节数组为null或长度不是6字节
     * @see #macBytesToString(byte[], boolean)
     * @see #macStringToBytes(String)
     */
    public static String macBytesToString(byte[] macBytes) {
        // 默认大写字符
        return macBytesToString(macBytes, true);
    }

    /**
     * 将MAC地址字节数组转换为指定格式的字符串
     * 
     * <p>功能说明：</p>
     * <ul>
     *   <li>支持大写和小写十六进制输出</li>
     *   <li>使用冒号（:）作为分隔符</li>
     *   <li>自动验证字节数组长度</li>
     *   <li>处理字节的符号位问题</li>
     * </ul>
     * 
     * <p>输出格式：</p>
     * <ul>
     *   <li>大写格式：<code>AA:BB:CC:DD:EE:FF</code></li>
     *   <li>小写格式：<code>aa:bb:cc:dd:ee:ff</code></li>
     * </ul>
     * 
     * <p>使用场景：</p>
     * <ul>
     *   <li>需要特定大小写格式的MAC地址显示</li>
     *   <li>网络配置文件的格式化</li>
     *   <li>用户界面的显示需求</li>
     *   <li>与其他系统的格式兼容</li>
     * </ul>
     * 
     * <p>使用示例：</p>
     * <pre>{@code
     * byte[] macBytes = {0x00, 0x11, 0x22, 0x33, 0x44, 0x55};
     * 
     * // 转换为大写格式
     * String macUpper = NetworkUtils.macBytesToString(macBytes, true);
     * System.out.println("大写格式: " + macUpper); // 输出：00:11:22:33:44:55
     * 
     * // 转换为小写格式
     * String macLower = NetworkUtils.macBytesToString(macBytes, false);
     * System.out.println("小写格式: " + macLower); // 输出：00:11:22:33:44:55
     * 
     * // 处理负数字节
     * byte[] negativeBytes = {(byte)0xFF, (byte)0xFE, 0x00, 0x01, 0x02, 0x03};
     * String negativeMac = NetworkUtils.macBytesToString(negativeBytes);
     * System.out.println("负数字节: " + negativeMac); // 输出：FF:FE:00:01:02:03
     * }</pre>
     * 
     * <p>技术细节：</p>
     * <ul>
     *   <li>使用位运算 <code>& 0xFF</code> 处理字节的符号位</li>
     *   <li>使用 <code>String.format()</code> 确保两位十六进制输出</li>
     *   <li>动态构建分隔符，避免末尾多余的分隔符</li>
     * </ul>
     * 
     * @param macBytes MAC地址字节数组，必须为6字节长度
     * @param uppercase 是否使用大写字母，true为大写，false为小写
     * @return 指定格式的MAC地址字符串
     * @throws IllegalArgumentException 如果字节数组为null或长度不是6字节
     * @see #macBytesToString(byte[])
     * @see #macStringToBytes(String)
     */
    public static String macBytesToString(byte[] macBytes, boolean uppercase) {

        Assert.notEmpty(macBytes , "MAC address byte array must not be empty");
        Assert.notEquals(macBytes.length , 6 , "MAC address byte array must be 6 bytes long");
        
        StringBuilder sb = new StringBuilder();
        String format = uppercase ? "%02X" : "%02x";
        
        for (int i = 0; i < macBytes.length; i++) {
            sb.append(String.format(format, macBytes[i] & 0xFF));
            if (i < macBytes.length - 1) {
                sb.append(":");
            }
        }
        
        return sb.toString();
    }

    /**
     * 将MAC地址字符串转换为字节数组
     * 
     * <p>功能说明：</p>
     * <ul>
     *   <li>支持多种分隔符格式的MAC地址字符串</li>
     *   <li>自动清理和标准化输入字符串</li>
     *   <li>验证MAC地址格式的有效性</li>
     *   <li>返回6字节的字节数组</li>
     * </ul>
     * 
     * <p>支持的输入格式：</p>
     * <ul>
     *   <li><code>AA:BB:CC:DD:EE:FF</code> - 冒号分隔（标准格式）</li>
     *   <li><code>AA-BB-CC-DD-EE-FF</code> - 连字符分隔</li>
     *   <li><code>AA.BB.CC.DD.EE.FF</code> - 点分隔</li>
     *   <li><code>AA BB CC DD EE FF</code> - 空格分隔</li>
     *   <li><code>AABBCCDDEEFF</code> - 无分隔符</li>
     *   <li><code>aa:bb:cc:dd:ee:ff</code> - 小写格式</li>
     *   <li><code>Aa:Bb:Cc:Dd:Ee:Ff</code> - 混合大小写</li>
     * </ul>
     * 
     * <p>转换过程：</p>
     * <ol>
     *   <li>移除所有分隔符和空格</li>
     *   <li>转换为大写格式</li>
     *   <li>验证长度（必须是12个十六进制字符）</li>
     *   <li>验证格式有效性</li>
     *   <li>转换为6字节数组</li>
     * </ol>
     * 
     * <p>使用场景：</p>
     * <ul>
     *   <li>配置文件中的MAC地址解析</li>
     *   <li>用户输入的MAC地址处理</li>
     *   <li>网络配置验证</li>
     *   <li>MAC地址比较操作</li>
     *   <li>数据库存储前的格式转换</li>
     * </ul>
     * 
     * <p>使用示例：</p>
     * <pre>{@code
     * // 解析不同格式的MAC地址
     * String[] macFormats = {
     *     "AA:BB:CC:DD:EE:FF",    // 冒号分隔
     *     "AA-BB-CC-DD-EE-FF",    // 连字符分隔
     *     "AA.BB.CC.DD.EE.FF",    // 点分隔
     *     "AA BB CC DD EE FF",    // 空格分隔
     *     "AABBCCDDEEFF"          // 无分隔符
     * };
     * 
     * for (String format : macFormats) {
     *     try {
     *         byte[] bytes = NetworkUtils.macStringToBytes(format);
     *         String converted = NetworkUtils.macBytesToString(bytes);
     *         System.out.println(format + " -> " + converted);
     *     } catch (IllegalArgumentException e) {
     *         System.err.println("无效的MAC地址格式: " + format);
     *     }
     * }
     * }</pre>
     * 
     * <p>错误处理：</p>
     * <ul>
     *   <li>空字符串或null值：抛出 <code>IllegalArgumentException</code></li>
     *   <li>长度不正确：抛出 <code>IllegalArgumentException</code></li>
     *   <li>格式无效：抛出 <code>IllegalArgumentException</code></li>
     * </ul>
     * 
     * @param macAddress MAC地址字符串，支持多种分隔符格式
     * @return MAC地址字节数组，长度为6字节
     * @throws IllegalArgumentException 如果MAC地址字符串格式无效
     * @see #macBytesToString(byte[])
     * @see #macBytesToString(byte[], boolean)
     * @see #isValidMacAddress(String)
     */
    public static byte[] macStringToBytes(String macAddress) {

        Assert.notBlank(macAddress , "MAC address must not be blank");
        
        // Remove all delimiters and spaces, convert to pure hexadecimal string
        String cleanMac = macAddress.replaceAll("[:\\-\\.\\s]", "").toUpperCase();

        // Validate length
        Assert.notEquals(cleanMac.length() , 12 , "MAC address must be 12 hexadecimal characters, current length: " + cleanMac.length());

        // Validate format
        Assert.isTrue(isValidMacAddress(cleanMac) , "MAC address string format is invalid: " + macAddress);
        
        // Convert to byte array
        byte[] macBytes = new byte[6];
        for (int i = 0; i < 6; i++) {
            int index = i * 2;
            macBytes[i] = (byte) Integer.parseInt(cleanMac.substring(index, index + 2), 16);
        }
        
        return macBytes;
    }

    /**
     * 验证MAC地址字符串格式是否有效
     * 
     * <p>验证功能：</p>
     * <ul>
     *   <li>检查MAC地址字符串的格式有效性</li>
     *   <li>支持多种分隔符格式</li>
     *   <li>自动清理和标准化输入</li>
     *   <li>返回布尔值表示验证结果</li>
     * </ul>
     * 
     * <p>验证规则：</p>
     * <ul>
     *   <li>字符串不能为null或空</li>
     *   <li>清理后必须是12个十六进制字符</li>
     *   <li>使用正则表达式验证格式</li>
     *   <li>异常情况下返回false而不是抛出异常</li>
     * </ul>
     * 
     * <p>支持的格式：</p>
     * <ul>
     *   <li><code>AA:BB:CC:DD:EE:FF</code> - 冒号分隔</li>
     *   <li><code>AA-BB-CC-DD-EE-FF</code> - 连字符分隔</li>
     *   <li><code>AA.BB.CC.DD.EE.FF</code> - 点分隔</li>
     *   <li><code>AA BB CC DD EE FF</code> - 空格分隔</li>
     *   <li><code>AABBCCDDEEFF</code> - 无分隔符</li>
     * </ul>
     * 
     * <p>使用场景：</p>
     * <ul>
     *   <li>用户输入验证</li>
     *   <li>配置文件验证</li>
     *   <li>网络配置检查</li>
     *   <li>数据导入验证</li>
     *   <li>表单验证</li>
     *   <li>API参数验证</li>
     * </ul>
     * 
     * <p>使用示例：</p>
     * <pre>{@code
     * // 基本验证
     * boolean isValid1 = NetworkUtils.isValidMacAddress("AA:BB:CC:DD:EE:FF");
     * System.out.println("AA:BB:CC:DD:EE:FF -> " + isValid1); // true
     * 
     * // 验证不同格式
     * String[] testMacs = {
     *     "AA:BB:CC:DD:EE:FF",    // 冒号分隔
     *     "AA-BB-CC-DD-EE-FF",    // 连字符分隔
     *     "AA.BB.CC.DD.EE.FF",    // 点分隔
     *     "AA BB CC DD EE FF",    // 空格分隔
     *     "AABBCCDDEEFF"          // 无分隔符
     * };
     * 
     * for (String mac : testMacs) {
     *     boolean isValid = NetworkUtils.isValidMacAddress(mac);
     *     System.out.println(mac + " -> " + isValid);
     * }
     * 
     * // 验证无效格式
     * String[] invalidMacs = {
     *     "AA:BB-CC:DD:EE:FF",    // 混合分隔符
     *     "AA:BB:CC:DD:EE",       // 长度不足
     *     "AA:BB:CC:DD:EE:FF:GG", // 长度过长
     *     "AA:BB:CC:DD:EE:GG",    // 包含无效字符
     *     "",                     // 空字符串
     *     null                    // null值
     * };
     * 
     * for (String mac : invalidMacs) {
     *     boolean isValid = NetworkUtils.isValidMacAddress(mac);
     *     System.out.println(mac + " -> " + isValid);
     * }
     * 
     * // 在用户输入验证中使用
     * Scanner scanner = new Scanner(System.in);
     * System.out.print("请输入MAC地址: ");
     * String userInput = scanner.nextLine();
     * 
     * if (NetworkUtils.isValidMacAddress(userInput)) {
     *     System.out.println("MAC地址格式有效");
     *     // 继续处理逻辑
     * } else {
     *     System.out.println("MAC地址格式无效，请重新输入");
     * }
     * }</pre>
     * 
     * <p>性能特点：</p>
     * <ul>
     *   <li>使用正则表达式进行快速验证</li>
     *   <li>异常安全，不会抛出异常</li>
     *   <li>适合频繁调用的验证场景</li>
     * </ul>
     * 
     * @param macAddress 要验证的MAC地址字符串
     * @return true表示MAC地址格式有效，false表示无效
     * @see #macStringToBytes(String)
     * @see #macBytesToString(byte[])
     * @see #isValidMacAddressStrict(String)
     * @see #MAC_ADDRESS_PATTERN
     * @see #MAC_ADDRESS_STRICT_PATTERN
     */
    public static boolean isValidMacAddress(String macAddress) {

        // 快速检查null和空字符串
        if (macAddress == null || macAddress.trim().isEmpty()) {
            return false;
        }
        
        String trimmedMac = macAddress.trim();
        
        // 检查是否包含混合分隔符
        if (containsMixedDelimiters(trimmedMac)) {
            return false;
        }

        // 使用预编译的正则表达式进行验证
        return MAC_ADDRESS_PATTERN.matcher(trimmedMac).matches();
    }
    
    /**
     * 检查MAC地址字符串是否包含混合分隔符
     * 
     * @param macAddress MAC地址字符串
     * @return true表示包含混合分隔符，false表示分隔符一致或无分隔符
     */
    private static boolean containsMixedDelimiters(String macAddress) {
        // 如果没有分隔符，返回false（无分隔符是有效的）
        if (!macAddress.contains(":") && !macAddress.contains("-") && 
            !macAddress.contains(".") && !macAddress.contains(" ")) {
            return false;
        }
        
        // 检查是否同时包含多种分隔符
        boolean hasColon = macAddress.contains(":");
        boolean hasHyphen = macAddress.contains("-");
        boolean hasDot = macAddress.contains(".");
        boolean hasSpace = macAddress.contains(" ");
        
        // 计算分隔符种类数量
        int delimiterCount = 0;
        if (hasColon) delimiterCount++;
        if (hasHyphen) delimiterCount++;
        if (hasDot) delimiterCount++;
        if (hasSpace) delimiterCount++;
        
        // 如果分隔符种类超过1种，说明是混合分隔符
        return delimiterCount > 1;
    }

    /**
     * 检测字符串是否是标准的计算机MAC地址（严格模式）
     *
     * <p>严格模式说明：</p>
     * <ul>
     *   <li>支持Windows标准格式：AA-BB-CC-DD-EE-FF（连字符分隔）</li>
     *   <li>支持Linux标准格式：AA:BB:CC:DD:EE:FF（冒号分隔）</li>
     *   <li>每个字节必须是两位十六进制数字</li>
     *   <li>不允许混合使用不同分隔符</li>
     *   <li>不允许无分隔符格式</li>
     *   <li>不允许其他分隔符（如点、空格等）</li>
     * </ul>
     *
     * <p>跨平台兼容性：</p>
     * <ul>
     *   <li>Windows系统通常使用连字符（-）分隔</li>
     *   <li>Linux系统通常使用冒号（:）分隔</li>
     *   <li>此方法同时支持两种格式，确保跨平台兼容</li>
     * </ul>
     *
     * <p>使用场景：</p>
     * <ul>
     *   <li>需要严格格式验证的场景</li>
     *   <li>系统配置要求标准格式</li>
     *   <li>与其他系统集成时的格式要求</li>
     *   <li>跨平台应用开发</li>
     *   <li>网络设备配置验证</li>
     * </ul>
     *
     * <p>使用示例：</p>
     * <pre>{@code
     * // Windows格式验证（连字符分隔）
     * boolean windowsValid = NetworkUtils.isValidMacAddressStrict("AA-BB-CC-DD-EE-FF");
     * System.out.println("Windows格式: " + windowsValid); // true
     * 
     * // Linux格式验证（冒号分隔）
     * boolean linuxValid = NetworkUtils.isValidMacAddressStrict("AA:BB:CC:DD:EE:FF");
     * System.out.println("Linux格式: " + linuxValid); // true
     * 
     * // 无效格式测试
     * boolean invalid1 = NetworkUtils.isValidMacAddressStrict("AA.BB.CC.DD.EE.FF"); // false
     * boolean invalid2 = NetworkUtils.isValidMacAddressStrict("AABBCCDDEEFF");       // false
     * boolean invalid3 = NetworkUtils.isValidMacAddressStrict("AA:BB-CC:DD:EE:FF"); // false
     * 
     * System.out.println("点分隔格式: " + invalid1);     // false
     * System.out.println("无分隔符格式: " + invalid2);   // false
     * System.out.println("混合分隔符: " + invalid3);     // false
     * }</pre>
     *
     * <p>性能说明：</p>
     * <ul>
     *   <li>使用预编译的正则表达式模式 <code>MAC_ADDRESS_STRICT_PATTERN</code></li>
     *   <li>避免重复编译正则表达式，提高性能</li>
     *   <li>适合频繁调用的验证场景</li>
     * </ul>
     *
     * @param macAddress 要检测的MAC地址字符串
     * @return true表示是有效的标准格式MAC地址，false表示无效
     * @see #isValidMacAddress(String)
     * @see #MAC_ADDRESS_STRICT_PATTERN
     * @see #MAC_ADDRESS_PATTERN
     */
    public static boolean isValidMacAddressStrict(String macAddress) {
        // 快速检查null和空字符串
        if (macAddress == null || macAddress.trim().isEmpty()) {
            return false;
        }

        // 检查是否包含混合分隔符
        if (containsMixedDelimiters(macAddress.trim())) {
            return false;
        }

        // 严格模式：只允许冒号分隔符
        return MAC_ADDRESS_STRICT_PATTERN.matcher(macAddress.trim()).matches();
    }

    /**
     * 获取网卡的MAC地址字符串表示
     * 
     * <p>功能说明：</p>
     * <ul>
     *   <li>安全地获取网卡的MAC地址</li>
     *   <li>自动处理null值和异常情况</li>
     *   <li>返回标准格式的MAC地址字符串</li>
     *   <li>如果无法获取则返回null</li>
     * </ul>
     * 
     * <p>获取过程：</p>
     * <ol>
     *   <li>检查网络接口对象是否为null</li>
     *   <li>调用 <code>getHardwareAddress()</code> 获取原始字节数组</li>
     *   <li>验证字节数组的有效性</li>
     *   <li>转换为标准字符串格式</li>
     *   <li>异常情况下返回null</li>
     * </ol>
     * 
     * <p>返回格式：</p>
     * <ul>
     *   <li>成功：<code>AA:BB:CC:DD:EE:FF</code> 格式的字符串</li>
     *   <li>失败：<code>null</code></li>
     * </ul>
     * 
     * <p>使用场景：</p>
     * <ul>
     *   <li>网卡信息显示</li>
     *   <li>网络配置管理</li>
     *   <li>日志记录</li>
     *   <li>网络故障诊断</li>
     *   <li>网络设备识别</li>
     * </ul>
     * 
     * <p>使用示例：</p>
     * <pre>{@code
     * // 获取所有网卡的MAC地址
     * List<NetworkInterface> interfaces = getAllNetworkInterfaces();
     * for (NetworkInterface iface : interfaces) {
     *     String macAddress = NetworkUtils.getMacAddress(iface);
     *     if (macAddress != null) {
     *         System.out.println(iface.getDisplayName() + ": " + macAddress);
     *     } else {
     *         System.out.println(iface.getDisplayName() + ": 无MAC地址");
     *     }
     * }
     * }</pre>
     * 
     * <p>注意事项：</p>
     * <ul>
     *   <li>虚拟网卡可能没有MAC地址</li>
     *   <li>某些网卡可能被禁用或故障</li>
     *   <li>权限不足可能影响MAC地址获取</li>
     *   <li>返回值null表示无法获取，需要调用者处理</li>
     * </ul>
     * 
     * @param networkInterface 网络接口对象
     * @return MAC地址字符串，如果无法获取则返回null
     * @throws NetworkException 如果获取硬件地址时发生网络异常
     * @see #macBytesToString(byte[])
     * @see #getAllNetworkInterfaces()
     * @see NetworkInterface#getHardwareAddress()
     */
    public static String getMacAddress(NetworkInterface networkInterface) {
        if (networkInterface == null) {
            return null;
        }
        byte[] macBytes;
        try {
            macBytes = networkInterface.getHardwareAddress();
        } catch (SocketException e) {
            throw new NetworkException(e);
        }
        return macBytesToString(macBytes);
    }

    /**
     * 获取本机所有未启用的网络接口（网卡）信息
     * 
     * <p>未启用网卡筛选原理：</p>
     * <ul>
     *   <li>调用 <code>getAllNetworkInterfaces()</code> 获取所有网络接口</li>
     *   <li>使用 <code>isUp()</code> 方法筛选出状态为未启用的接口</li>
     *   <li>包括已禁用、故障或配置错误的网络接口</li>
     * </ul>
     * 
     * <p>未启用状态说明：</p>
     * <ul>
     *   <li><code>isUp()</code> 返回 <code>false</code>：网卡已禁用或存在故障</li>
     *   <li>可能的原因：手动禁用、驱动问题、硬件故障、配置错误</li>
     * </ul>
     * 
     * <p>使用场景：</p>
     * <ul>
     *   <li>网络故障诊断和排除</li>
     *   <li>网卡状态监控</li>
     *   <li>网络配置问题排查</li>
     *   <li>系统维护和故障恢复</li>
     * </ul>
     * 
     * <p>使用示例：</p>
     * <pre>{@code
     * // 获取所有未启用的网卡
     * List<NetworkInterface> disabledInterfaces = NetworkUtils.getDisabledNetworkInterfaces();
     * 
     * // 显示未启用网卡的信息
     * for (NetworkInterface networkInterface : disabledInterfaces) {
     *     System.out.println("未启用网卡: " + networkInterface.getDisplayName());
     *     System.out.println("接口名称: " + networkInterface.getName());
     *     System.out.println("MTU: " + networkInterface.getMTU());
     *     
     *     // 尝试获取IP地址（可能为空）
     *     Enumeration<InetAddress> addresses = networkInterface.getInetAddresses();
     *     if (addresses.hasMoreElements()) {
     *         while (addresses.hasMoreElements()) {
     *             InetAddress address = addresses.nextElement();
     *             System.out.println("  IP地址: " + address.getHostAddress());
     *         }
     *     } else {
     *         System.out.println("  无IP地址配置");
     *     }
     * }
     * 
     * // 统计未启用网卡数量
     * System.out.println("未启用网卡总数: " + disabledInterfaces.size());
     * 
     * // 检查是否有网卡被禁用
     * if (!disabledInterfaces.isEmpty()) {
     *     System.out.println("发现 " + disabledInterfaces.size() + " 个未启用的网卡");
     *     // 可以尝试启用或诊断问题
     * } else {
     *     System.out.println("所有网卡都已启用");
     * }
     * }</pre>
     * 
     * @return 包含所有未启用网络接口的列表，如果没有未启用的接口则返回空列表
     * @throws SecurityException 如果没有足够的权限访问网络接口信息
     * @throws NetworkException 如果获取网络接口信息时发生I/O错误
     * @see #getAllNetworkInterfaces()
     * @see #getActiveNetworkInterfaces()
     * @see NetworkInterface#isUp()
     */
    public static List<NetworkInterface> getDisabledNetworkInterfaces() {
        List<NetworkInterface> disabledInterfaces = new ArrayList<>();
        try {
            for (NetworkInterface networkInterface : getAllNetworkInterfaces()) {
                if (!networkInterface.isUp()) {
                    disabledInterfaces.add(networkInterface);
                }
            }
        } catch (SocketException e) {
            throw new NetworkException(e);
        }

        return disabledInterfaces;
    }

    /**
     * 获取本机所有启用的物理网络接口（网卡）信息
     * 
     * <p>启用物理网卡筛选原理：</p>
     * <ul>
     *   <li>调用 <code>getAllNetworkInterfaces()</code> 获取所有网络接口</li>
     *   <li>使用 <code>isUp()</code> 方法筛选出状态为启用的接口</li>
     *   <li>使用 <code>isVirtual()</code> 方法筛选出非虚拟的接口</li>
     *   <li>返回真实硬件设备且正在工作的网卡</li>
     * </ul>
     * 
     * <p>启用物理网卡特征：</p>
     * <ul>
     *   <li><code>isUp()</code> 返回 <code>true</code>：网卡已启用且正常工作</li>
     *   <li><code>isVirtual()</code> 返回 <code>false</code>：真实的网络硬件设备</li>
     *   <li>通常具有固定的硬件地址（MAC地址）</li>
     *   <li>支持硬件级别的网络功能</li>
     * </ul>
     * 
     * <p>使用场景：</p>
     * <ul>
     *   <li>硬件网络设备管理和监控</li>
     *   <li>网络性能优化和调优</li>
     *   <li>硬件故障诊断和排除</li>
     *   <li>网络拓扑分析和规划</li>
     *   <li>系统资源使用统计</li>
     * </ul>
     * 
     * <p>使用示例：</p>
     * <pre>{@code
     * // 获取所有启用的物理网卡
     * List<NetworkInterface> activePhysicalInterfaces = NetworkUtils.getActivePhysicalNetworkInterfaces();
     * 
     * // 显示启用物理网卡信息
     * for (NetworkInterface networkInterface : activePhysicalInterfaces) {
     *     System.out.println("启用物理网卡: " + networkInterface.getDisplayName());
     *     System.out.println("接口名称: " + networkInterface.getName());
     *     System.out.println("MTU: " + networkInterface.getMTU());
     *     
     *     // 获取硬件地址（MAC地址）
     *     String macAddress = getMacAddress(networkInterface);
     *     if (macAddress != null) {
     *         System.out.println("MAC地址: " + macAddress);
     *     }
     *     
     *     // 获取IP地址
     *     Enumeration<InetAddress> addresses = networkInterface.getInetAddresses();
     *     while (addresses.hasMoreElements()) {
     *         InetAddress address = addresses.nextElement();
     *         System.out.println("  IP地址: " + address.getHostAddress());
     *     }
     * }
     * 
     * // 统计启用物理网卡数量
     * System.out.println("启用物理网卡总数: " + activePhysicalInterfaces.size());
     * 
     * // 检查网络连接状态
     * if (!activePhysicalInterfaces.isEmpty()) {
     *     System.out.println("检测到 " + activePhysicalInterfaces.size() + " 个可用的物理网络连接");
     *     // 可以执行网络相关操作
     * } else {
     *     System.out.println("没有可用的物理网络连接");
     *     // 可能需要检查网络配置或硬件状态
     * }
     * }</pre>
     * 
     * @return 包含所有启用物理网络接口的列表，如果没有启用的物理接口则返回空列表
     * @throws SecurityException 如果没有足够的权限访问网络接口信息
     * @throws NetworkException 如果获取网络接口信息时发生I/O错误
     * @see #getAllNetworkInterfaces()
     * @see #getPhysicalNetworkInterfaces()
     * @see #getActiveNetworkInterfaces()
     * @see NetworkInterface#isUp()
     * @see NetworkInterface#isVirtual()
     */
    public static List<NetworkInterface> getActivePhysicalNetworkInterfaces() {
        List<NetworkInterface> activePhysicalInterfaces = new ArrayList<>();
        try {
            for (NetworkInterface networkInterface : getPhysicalNetworkInterfaces()) {
                if (networkInterface.isUp()) {
                    activePhysicalInterfaces.add(networkInterface);
                }
            }
        } catch (SocketException e) {
            throw new NetworkException(e);
        }

        return activePhysicalInterfaces;
    }

    /**
     * 获取本机所有未启用的物理网络接口（网卡）信息
     * 
     * <p>未启用物理网卡筛选原理：</p>
     * <ul>
     *   <li>调用 <code>getAllNetworkInterfaces()</code> 获取所有网络接口</li>
     *   <li>使用 <code>isUp()</code> 方法筛选出状态为未启用的接口</li>
     *   <li>使用 <code>isVirtual()</code> 方法筛选出非虚拟的接口</li>
     *   <li>返回真实硬件设备但被禁用的网卡</li>
     * </ul>
     * 
     * <p>未启用物理网卡特征：</p>
     * <ul>
     *   <li><code>isUp()</code> 返回 <code>false</code>：网卡已禁用或存在故障</li>
     *   <li><code>isVirtual()</code> 返回 <code>false</code>：真实的网络硬件设备</li>
     *   <li>可能的原因：手动禁用、驱动问题、硬件故障、配置错误</li>
     * </ul>
     * 
     * <p>使用场景：</p>
     * <ul>
     *   <li>硬件网卡故障诊断</li>
     *   <li>网络配置问题排查</li>
     *   <li>系统维护和故障恢复</li>
     *   <li>硬件资源使用分析</li>
     *   <li>网络设备管理</li>
     * </ul>
     * 
     * <p>使用示例：</p>
     * <pre>{@code
     * // 获取所有未启用的物理网卡
     * List<NetworkInterface> disabledPhysicalInterfaces = NetworkUtils.getDisabledPhysicalNetworkInterfaces();
     * 
     * // 显示未启用物理网卡信息
     * for (NetworkInterface networkInterface : disabledPhysicalInterfaces) {
     *     System.out.println("未启用物理网卡: " + networkInterface.getDisplayName());
     *     System.out.println("接口名称: " + networkInterface.getName());
     *     System.out.println("MTU: " + networkInterface.getMTU());
     *     
     *     // 尝试获取硬件地址（可能为null）
     *     String macAddress = getMacAddress(networkInterface);
     *     if (macAddress != null) {
     *         System.out.println("MAC地址: " + macAddress);
     *     } else {
     *         System.out.println("MAC地址: 无法获取");
     *     }
     *     
     *     // 尝试获取IP地址（通常为空）
     *     Enumeration<InetAddress> addresses = networkInterface.getInetAddresses();
     *     if (addresses.hasMoreElements()) {
     *         while (addresses.hasMoreElements()) {
     *             InetAddress address = addresses.nextElement();
     *             System.out.println("  IP地址: " + address.getHostAddress());
     *         }
     *     } else {
     *         System.out.println("  无IP地址配置");
     *     }
     * }
     * 
     * // 统计未启用物理网卡数量
     * System.out.println("未启用物理网卡总数: " + disabledPhysicalInterfaces.size());
     * 
     * // 检查是否有物理网卡被禁用
     * if (!disabledPhysicalInterfaces.isEmpty()) {
     *     System.out.println("发现 " + disabledPhysicalInterfaces.size() + " 个未启用的物理网卡");
     *     // 可以尝试启用或诊断问题
     * } else {
     *     System.out.println("所有物理网卡都已启用");
     * }
     * }</pre>
     * 
     * @return 包含所有未启用物理网络接口的列表，如果没有未启用的物理接口则返回空列表
     * @throws SecurityException 如果没有足够的权限访问网络接口信息
     * @throws NetworkException 如果获取网络接口信息时发生I/O错误
     * @see #getAllNetworkInterfaces()
     * @see #getPhysicalNetworkInterfaces()
     * @see #getDisabledNetworkInterfaces()
     * @see NetworkInterface#isUp()
     * @see NetworkInterface#isVirtual()
     */
    public static List<NetworkInterface> getDisabledPhysicalNetworkInterfaces() {
        List<NetworkInterface> disabledPhysicalInterfaces = new ArrayList<>();
        try {
            for (NetworkInterface networkInterface : getPhysicalNetworkInterfaces()) {
                if (!networkInterface.isUp()) {
                    disabledPhysicalInterfaces.add(networkInterface);
                }
            }
        } catch (SocketException e) {
            throw new NetworkException(e);
        }

        return disabledPhysicalInterfaces;
    }

    /**
     * 获取本机所有启用的虚拟网络接口（网卡）信息
     * 
     * <p>启用虚拟网卡筛选原理：</p>
     * <ul>
     *   <li>调用 <code>getAllNetworkInterfaces()</code> 获取所有网络接口</li>
     *   <li>使用 <code>isUp()</code> 方法筛选出状态为启用的接口</li>
     *   <li>使用 <code>isVirtual()</code> 方法筛选出虚拟的接口</li>
     *   <li>返回软件创建的且正在工作的虚拟网卡</li>
     * </ul>
     * 
     * <p>启用虚拟网卡特征：</p>
     * <ul>
     *   <li><code>isUp()</code> 返回 <code>true</code>：虚拟网卡已启用且正常工作</li>
     *   <li><code>isVirtual()</code> 返回 <code>true</code>：软件创建的虚拟网络接口</li>
     *   <li>包括VPN、虚拟机、容器、隧道等虚拟网络接口</li>
     *   <li>支持高级网络功能，如网络隔离、流量控制等</li>
     * </ul>
     * 
     * <p>使用场景：</p>
     * <ul>
     *   <li>虚拟网络环境管理</li>
     *   <li>VPN连接状态监控</li>
     *   <li>虚拟机网络配置</li>
     *   <li>容器网络管理</li>
     *   <li>网络虚拟化部署</li>
     *   <li>网络安全策略实施</li>
     *   <li>网络流量分析和监控</li>
     * </ul>
     * 
     * <p>使用示例：</p>
     * <pre>{@code
     * // 获取所有启用的虚拟网卡
     * List<NetworkInterface> activeVirtualInterfaces = NetworkUtils.getActiveVirtualNetworkInterfaces();
     * 
     * // 显示启用虚拟网卡信息
     * for (NetworkInterface networkInterface : activeVirtualInterfaces) {
     *     System.out.println("启用虚拟网卡: " + networkInterface.getDisplayName());
     *     System.out.println("接口名称: " + networkInterface.getName());
     *     System.out.println("是否启用: " + networkInterface.isUp());
     *     System.out.println("是否回环: " + networkInterface.isLoopback());
     *     System.out.println("MTU: " + networkInterface.getMTU());
     *     
     *     // 获取IP地址
     *     Enumeration<InetAddress> addresses = networkInterface.getInetAddresses();
     *     while (addresses.hasMoreElements()) {
     *         InetAddress address = addresses.nextElement();
     *         System.out.println("  IP地址: " + address.getHostAddress());
     *     }
     *     
     *     // 获取硬件地址（可能为null）
     *     String macAddress = getMacAddress(networkInterface);
     *     if (macAddress != null) {
     *         System.out.println("MAC地址: " + macAddress);
     *     } else {
     *         System.out.println("MAC地址: 动态生成或无MAC地址");
     *     }
     * }
     * 
     * // 统计启用虚拟网卡数量
     * System.out.println("启用虚拟网卡总数: " + activeVirtualInterfaces.size());
     * 
     * // 检查虚拟网络环境
     * if (!activeVirtualInterfaces.isEmpty()) {
     *     System.out.println("检测到 " + activeVirtualInterfaces.size() + " 个可用的虚拟网络连接");
     *     
     *     // 分类统计不同类型的虚拟网卡
     *     long vpnCount = activeVirtualInterfaces.stream()
     *         .filter(iface -> {
     *             String name = iface.getName().toLowerCase();
     *             return name.contains("tun") || name.contains("tap") || 
     *                    name.contains("vpn") || name.contains("wireguard");
     *         })
     *         .count();
     *     
     *     long vmCount = activeVirtualInterfaces.stream()
     *         .filter(iface -> {
     *             String name = iface.getName().toLowerCase();
     *             return name.contains("vmnet") || name.contains("vbox") || 
     *                    name.contains("virbr") || name.contains("docker");
     *         })
     *         .count();
     *     
     *     System.out.println("VPN接口数: " + vpnCount);
     *     System.out.println("虚拟机接口数: " + vmCount);
     * } else {
     *     System.out.println("没有可用的虚拟网络连接");
     * }
     * }</pre>
     * 
     * @return 包含所有启用虚拟网络接口的列表，如果没有启用的虚拟接口则返回空列表
     * @throws SecurityException 如果没有足够的权限访问网络接口信息
     * @throws NetworkException 如果获取网络接口信息时发生I/O错误
     * @see #getAllNetworkInterfaces()
     * @see #getVirtualNetworkInterfaces()
     * @see #getActiveNetworkInterfaces()
     * @see NetworkInterface#isUp()
     * @see NetworkInterface#isVirtual()
     */
    public static List<NetworkInterface> getActiveVirtualNetworkInterfaces() {
        List<NetworkInterface> activeVirtualInterfaces = new ArrayList<>();
        try {
            for (NetworkInterface networkInterface : getVirtualNetworkInterfaces()) {
                if (networkInterface.isUp()) {
                    activeVirtualInterfaces.add(networkInterface);
                }
            }
        } catch (SocketException e) {
            throw new NetworkException(e);
        }

        return activeVirtualInterfaces;
    }

    /**
     * 获取本机所有未启用的虚拟网络接口（网卡）信息
     * 
     * <p>未启用虚拟网卡筛选原理：</p>
     * <ul>
     *   <li>调用 <code>getAllNetworkInterfaces()</code> 获取所有网络接口</li>
     *   <li>使用 <code>isUp()</code> 方法筛选出状态为未启用的接口</li>
     *   <li>使用 <code>isVirtual()</code> 方法筛选出虚拟的接口</li>
     *   <li>返回软件创建的但被禁用的虚拟网卡</li>
     * </ul>
     * 
     * <p>未启用虚拟网卡特征：</p>
     * <ul>
     *   <li><code>isUp()</code> 返回 <code>false</code>：虚拟网卡已禁用或存在故障</li>
     *   <li><code>isVirtual()</code> 返回 <code>true</code>：软件创建的虚拟网络接口</li>
     *   <li>可能的原因：服务停止、配置错误、权限问题、资源不足</li>
     *   <li>包括已停止的VPN、已关闭的虚拟机、已停止的容器等</li>
     * </ul>
     * 
     * <p>使用场景：</p>
     * <ul>
     *   <li>虚拟网络服务状态监控</li>
     *   <li>VPN连接问题诊断</li>
     *   <li>虚拟机网络配置检查</li>
     *   <li>容器网络状态验证</li>
     *   <li>虚拟网络环境故障排除</li>
     * </ul>
     * 
     * <p>使用示例：</p>
     * <pre>{@code
     * // 获取所有未启用的虚拟网卡
     * List<NetworkInterface> disabledVirtualInterfaces = NetworkUtils.getDisabledVirtualNetworkInterfaces();
     * 
     * // 显示未启用虚拟网卡信息
     * for (NetworkInterface networkInterface : disabledVirtualInterfaces) {
     *     System.out.println("未启用虚拟网卡: " + networkInterface.getDisplayName());
     *     System.out.println("接口名称: " + networkInterface.getName());
     *     System.out.println("是否启用: " + networkInterface.isUp());
     *     System.out.println("是否回环: " + networkInterface.isLoopback());
     *     System.out.println("MTU: " + networkInterface.getMTU());
     *     
     *     // 尝试获取IP地址（通常为空）
     *     Enumeration<InetAddress> addresses = networkInterface.getInetAddresses();
     *     if (addresses.hasMoreElements()) {
     *         while (addresses.hasMoreElements()) {
     *             InetAddress address = addresses.nextElement();
     *             System.out.println("  IP地址: " + address.getHostAddress());
     *         }
     *     } else {
     *         System.out.println("  无IP地址配置");
     *     }
     *     
     *     // 尝试获取硬件地址（可能为null）
     *     String macAddress = getMacAddress(networkInterface);
     *     if (macAddress != null) {
     *         System.out.println("MAC地址: " + macAddress);
     *     } else {
     *         System.out.println("MAC地址: 无法获取");
     *     }
     * }
     * 
     * // 统计未启用虚拟网卡数量
     * System.out.println("未启用虚拟网卡总数: " + disabledVirtualInterfaces.size());
     * 
     * // 检查虚拟网络服务状态
     * if (!disabledVirtualInterfaces.isEmpty()) {
     *     System.out.println("发现 " + disabledVirtualInterfaces.size() + " 个未启用的虚拟网卡");
     *     
     *     // 分类统计不同类型的未启用虚拟网卡
     *     long vpnCount = disabledVirtualInterfaces.stream()
     *         .filter(iface -> {
     *             String name = iface.getName().toLowerCase();
     *             return name.contains("tun") || name.contains("tap") || 
     *                    name.contains("vpn") || name.contains("wireguard");
     *         })
     *         .count();
     *     
     *     long vmCount = disabledVirtualInterfaces.stream()
     *         .filter(iface -> {
     *             String name = iface.getName().toLowerCase();
     *             return name.contains("vmnet") || name.contains("vbox") || 
     *                    name.contains("virbr") || name.contains("docker");
     *         })
     *         .count();
     *     
     *     System.out.println("未启用VPN接口数: " + vpnCount);
     *     System.out.println("未启用虚拟机接口数: " + vmCount);
     *     
     *     // 可以尝试启动相关服务
     *     if (vpnCount > 0) {
     *         System.out.println("建议检查VPN服务状态");
     *     }
     *     if (vmCount > 0) {
     *         System.out.println("建议检查虚拟机服务状态");
     *     }
     * } else {
     *     System.out.println("所有虚拟网卡都已启用");
     * }
     * }</pre>
     * 
     * @return 包含所有未启用虚拟网络接口的列表，如果没有未启用的虚拟接口则返回空列表
     * @throws SecurityException 如果没有足够的权限访问网络接口信息
     * @throws NetworkException 如果获取网络接口信息时发生I/O错误
     * @see #getAllNetworkInterfaces()
     * @see #getVirtualNetworkInterfaces()
     * @see #getDisabledNetworkInterfaces()
     * @see NetworkInterface#isUp()
     * @see NetworkInterface#isVirtual()
     */
    public static List<NetworkInterface> getDisabledVirtualNetworkInterfaces() {
        List<NetworkInterface> disabledVirtualInterfaces = new ArrayList<>();
        try {
            for (NetworkInterface networkInterface : getVirtualNetworkInterfaces()) {
                if (!networkInterface.isUp()) {
                    disabledVirtualInterfaces.add(networkInterface);
                }
            }
        } catch (SocketException e) {
            throw new NetworkException(e);
        }

        return disabledVirtualInterfaces;
    }

    /**
     * 获取指定网卡的所有IPv4地址
     * 
     * <p>IPv4地址获取原理：</p>
     * <ul>
     *   <li>调用 <code>networkInterface.getInetAddresses()</code> 获取网卡的所有IP地址</li>
     *   <li>使用 <code>instanceof Inet4Address</code> 筛选出IPv4地址</li>
     *   <li>排除回环地址和无效地址</li>
     *   <li>返回有效的IPv4地址列表</li>
     * </ul>
     * 
     * <p>IPv4地址特征：</p>
     * <ul>
     *   <li>32位地址，通常表示为四个点分隔的十进制数</li>
     *   <li>格式：xxx.xxx.xxx.xxx（如192.168.1.100）</li>
     *   <li>包括公网IP、内网IP、回环IP等</li>
     *   <li>支持子网掩码和CIDR表示法</li>
     * </ul>
     * 
     * <p>使用场景：</p>
     * <ul>
     *   <li>网卡IP地址配置管理</li>
     *   <li>网络配置验证和诊断</li>
     *   <li>IP地址冲突检测</li>
     *   <li>网络拓扑分析</li>
     *   <li>防火墙规则配置</li>
     * </ul>
     * 
     * <p>使用示例：</p>
     * <pre>{@code
     * // 获取指定网卡的所有IPv4地址
     * NetworkInterface networkInterface = getAllNetworkInterfaces().get(0);
     * List<String> ipv4Addresses = NetworkUtils.getIPv4Addresses(networkInterface);
     * 
     * if (!ipv4Addresses.isEmpty()) {
     *     System.out.println("网卡 " + networkInterface.getDisplayName() + " 的IPv4地址:");
     *     for (String ip : ipv4Addresses) {
     *         System.out.println("  " + ip);
     *         
     *         // 检查是否为内网地址
     *         if (isPrivateIPv4Address(ip)) {
     *             System.out.println("    (内网地址)");
     *         } else {
     *             System.out.println("    (公网地址)");
     *         }
     *     }
     * } else {
     *     System.out.println("该网卡没有配置IPv4地址");
     * }
     * 
     * // 批量处理所有网卡的IPv4地址
     * List<NetworkInterface> allInterfaces = getAllNetworkInterfaces();
     * for (NetworkInterface iface : allInterfaces) {
     *     List<String> ipv4List = getIPv4Addresses(iface);
     *     if (!ipv4List.isEmpty()) {
     *         System.out.println(iface.getDisplayName() + " IPv4地址: " + ipv4List);
     *     }
     * }
     * 
     * // 统计所有网卡的IPv4地址数量
     * long totalIPv4Count = allInterfaces.stream()
     *     .mapToLong(iface -> getIPv4Addresses(iface).size())
     *     .sum();
     * System.out.println("系统总IPv4地址数: " + totalIPv4Count);
     * }</pre>
     * 
     * @param networkInterface 网络接口对象，不能为null
     * @return 包含所有IPv4地址的列表，如果没有IPv4地址则返回空列表
     * @throws IllegalArgumentException 如果网络接口参数为null
     * @throws NetworkException 如果获取网络地址时发生网络异常
     * @see #getIPv6Addresses(NetworkInterface)
     * @see #getAllLocalIPAddresses()
     * @see #isPrivateIPv4Address(String)
     * @see NetworkInterface#getInetAddresses()
     * @see Inet4Address
     */
    public static List<String> getIPv4Addresses(NetworkInterface networkInterface) {
        return getIPv4AddressObjects(networkInterface)
                .stream()
                .map(Inet4Address::getHostAddress)
                .collect(Collectors.toList());
    }

    /**
     * 获取指定网卡的所有IPv6地址
     * 
     * <p>IPv6地址获取原理：</p>
     * <ul>
     *   <li>调用 <code>networkInterface.getInetAddresses()</code> 获取网卡的所有IP地址</li>
     *   <li>使用 <code>instanceof Inet6Address</code> 筛选出IPv6地址</li>
     *   <li>排除回环地址和无效地址</li>
     *   <li>返回有效的IPv6地址列表</li>
     * </ul>
     * 
     * <p>IPv6地址特征：</p>
     * <ul>
     *   <li>128位地址，通常表示为八组冒号分隔的十六进制数</li>
     *   <li>格式：xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx</li>
     *   <li>支持地址压缩（::）和省略前导零</li>
     *   <li>包括全球单播地址、链路本地地址、唯一本地地址等</li>
     *   <li>支持无状态地址自动配置（SLAAC）</li>
     * </ul>
     * 
     * <p>使用场景：</p>
     * <ul>
     *   <li>IPv6网络配置管理</li>
     *   <li>双栈网络环境支持</li>
     *   <li>IPv6地址冲突检测</li>
     *   <li>网络协议栈验证</li>
     *   <li>IPv6防火墙规则配置</li>
     *   <li>网络现代化升级支持</li>
     * </ul>
     * 
     * <p>使用示例：</p>
     * <pre>{@code
     * // 获取指定网卡的所有IPv6地址
     * NetworkInterface networkInterface = getAllNetworkInterfaces().get(0);
     * List<String> ipv6Addresses = NetworkUtils.getIPv6Addresses(networkInterface);
     * 
     * if (!ipv6Addresses.isEmpty()) {
     *     System.out.println("网卡 " + networkInterface.getDisplayName() + " 的IPv6地址:");
     *     for (String ip : ipv6Addresses) {
     *         System.out.println("  " + ip);
     *         
     *         // 检查是否为内网地址
     *         if (isPrivateIPv6Address(ip)) {
     *             System.out.println("    (内网地址)");
     *         } else {
     *             System.out.println("    (公网地址)");
     *         }
     *         
     *         // 检查是否为IPv4映射的IPv6地址
     *         if (isIPv4MappedIPv6Address(ip)) {
     *             String ipv4 = extractIPv4FromMappedIPv6(ip);
     *             System.out.println("    (IPv4映射地址，对应IPv4: " + ipv4 + ")");
     *         }
     *     }
     * } else {
     *     System.out.println("该网卡没有配置IPv6地址");
     * }
     * 
     * // 检查系统IPv6支持情况
     * if (isIPv6Supported()) {
     *     System.out.println("系统支持IPv6");
     *     
     *     // 统计所有网卡的IPv6地址
     *     List<NetworkInterface> allInterfaces = getAllNetworkInterfaces();
     *     long totalIPv6Count = allInterfaces.stream()
     *         .mapToLong(iface -> getIPv6Addresses(iface).size())
     *         .sum();
     *     System.out.println("系统总IPv6地址数: " + totalIPv6Count);
     *     
     *     // 查找启用的IPv6网卡
     *     List<NetworkInterface> ipv6Interfaces = allInterfaces.stream()
     *         .filter(iface -> !getIPv6Addresses(iface).isEmpty())
     *         .collect(Collectors.toList());
     *     System.out.println("配置IPv6的网卡数: " + ipv6Interfaces.size());
     * } else {
     *     System.out.println("系统不支持IPv6");
     * }
     * 
     * // 批量处理所有网卡的IPv6地址
     * for (NetworkInterface iface : getAllNetworkInterfaces()) {
     *     List<String> ipv6List = getIPv6Addresses(iface);
     *     if (!ipv6List.isEmpty()) {
     *         System.out.println(iface.getDisplayName() + " IPv6地址: " + ipv6List);
     *     }
     * }
     * }</pre>
     * 
     * @param networkInterface 网络接口对象，不能为null
     * @return 包含所有IPv6地址的列表，如果没有IPv6地址则返回空列表
     * @throws IllegalArgumentException 如果网络接口参数为null
     * @throws NetworkException 如果获取网络地址时发生网络异常
     * @see #getIPv4Addresses(NetworkInterface)
     * @see #isPrivateIPv6Address(String)
     * @see #isIPv4MappedIPv6Address(String)
     * @see #extractIPv4FromMappedIPv6(String)
     * @see NetworkInterface#getInetAddresses()
     * @see Inet6Address
     */
    public static List<String> getIPv6Addresses(NetworkInterface networkInterface) {
        return getIPv6AddressObjects(networkInterface)
                .stream()
                .map(Inet6Address::getHostAddress)
                .collect(Collectors.toList());
    }

    /**
     * 获取指定网卡的所有IPv4地址（返回Inet4Address对象）
     * 
     * <p>IPv4地址获取原理：</p>
     * <ul>
     *   <li>调用 <code>networkInterface.getInetAddresses()</code> 获取网卡的所有IP地址</li>
     *   <li>使用 <code>instanceof Inet4Address</code> 筛选出IPv4地址</li>
     *   <li>直接返回 <code>Inet4Address</code> 对象，保留完整的地址信息</li>
     *   <li>支持地址验证、网络前缀长度等高级功能</li>
     * </ul>
     * 
     * <p>Inet4Address对象优势：</p>
     * <ul>
     *   <li>提供完整的IPv4地址信息</li>
     *   <li>支持地址验证和格式检查</li>
     *   <li>可以获取网络前缀长度（子网掩码）</li>
     *   <li>支持地址范围计算和CIDR操作</li>
     *   <li>提供地址类型判断（公网、内网、回环等）</li>
     * </ul>
     * 
     * <p>使用场景：</p>
     * <ul>
     *   <li>需要完整IPv4地址信息的场景</li>
     *   <li>网络地址计算和CIDR操作</li>
     *   <li>地址类型判断和分类</li>
     *   <li>网络配置验证和诊断</li>
     *   <li>高级网络编程和工具开发</li>
     * </ul>
     * 
     * <p>使用示例：</p>
     * <pre>{@code
     * // 获取指定网卡的所有IPv4地址对象
     * NetworkInterface networkInterface = getAllNetworkInterfaces().get(0);
     * List<Inet4Address> ipv4Addresses = NetworkUtils.getIPv4AddressObjects(networkInterface);
     * 
     * if (!ipv4Addresses.isEmpty()) {
     *     System.out.println("网卡 " + networkInterface.getDisplayName() + " 的IPv4地址:");
     *     for (Inet4Address address : ipv4Addresses) {
     *         System.out.println("  " + address.getHostAddress());
     *         
     *         // 检查地址类型
     *         if (address.isLoopbackAddress()) {
     *             System.out.println("    (回环地址)");
     *         } else if (address.isLinkLocalAddress()) {
     *             System.out.println("    (链路本地地址)");
     *         } else if (address.isSiteLocalAddress()) {
     *             System.out.println("    (站点本地地址)");
     *         } else if (address.isMulticastAddress()) {
     *             System.out.println("    (多播地址)");
     *         } else {
     *             System.out.println("    (全球单播地址)");
     *         }
     *         
     *         // 检查是否为内网地址
     *         if (isPrivateIPv4Address(address.getHostAddress())) {
     *             System.out.println("    (内网地址)");
     *         } else {
     *             System.out.println("    (公网地址)");
     *         }
     *     }
     * } else {
     *     System.out.println("该网卡没有配置IPv4地址");
     * }
     * 
     * // 批量处理所有网卡的IPv4地址对象
     * List<NetworkInterface> allInterfaces = getAllNetworkInterfaces();
     * for (NetworkInterface iface : allInterfaces) {
     *     List<Inet4Address> ipv4List = getIPv4AddressObjects(iface);
     *     if (!ipv4List.isEmpty()) {
     *         System.out.println(iface.getDisplayName() + " IPv4地址对象数: " + ipv4List.size());
     *         
     *         // 统计不同类型的地址
     *         long loopbackCount = ipv4List.stream()
     *             .filter(Inet4Address::isLoopbackAddress)
     *             .count();
     *         long privateCount = ipv4List.stream()
     *             .filter(addr -> isPrivateIPv4Address(addr.getHostAddress()))
     *             .count();
     *         
     *         System.out.println("  回环地址: " + loopbackCount);
     *         System.out.println("  内网地址: " + privateCount);
     *         System.out.println("  公网地址: " + (ipv4List.size() - privateCount));
     *     }
     * }
     * 
     * // 地址范围计算示例
     * for (Inet4Address address : ipv4Addresses) {
     *     String ip = address.getHostAddress();
     *     // 假设子网掩码为24位
     *     IPRange range = getIPRange(ip, 24);
     *     if (range != null) {
     *         System.out.println("地址 " + ip + "/24 的范围:");
     *         System.out.println("  起始IP: " + range.getStartIP());
     *         System.out.println("  结束IP: " + range.getEndIP());
     *     }
     * }
     * }</pre>
     * 
     * @param networkInterface 网络接口对象，不能为null
     * @return 包含所有IPv4地址对象的列表，如果没有IPv4地址则返回空列表
     * @throws IllegalArgumentException 如果网络接口参数为null
     * @throws NetworkException 如果获取网络地址时发生网络异常
     * @see #getIPv4Addresses(NetworkInterface)
     * @see #getIPv6AddressObjects(NetworkInterface)
     * @see #isPrivateIPv4Address(String)
     * @see #getIPRange(String, int)
     * @see NetworkInterface#getInetAddresses()
     * @see Inet4Address
     */
    public static List<Inet4Address> getIPv4AddressObjects(NetworkInterface networkInterface) {
        Assert.notNull(networkInterface, "Network interface must not be null");
        
        List<Inet4Address> ipv4Addresses = new ArrayList<>();
        try {
            Enumeration<InetAddress> addresses = networkInterface.getInetAddresses();
            while (addresses.hasMoreElements()) {
                InetAddress address = addresses.nextElement();
                if (address instanceof Inet4Address) {
                    ipv4Addresses.add((Inet4Address) address);
                }
            }
        } catch (Exception e) {
            throw new NetworkException("Failed to get IPv4 address objects for network interface: " + networkInterface.getName(), e);
        }
        
        return ipv4Addresses;
    }

    /**
     * 获取指定网卡的所有IPv6地址（返回Inet6Address对象）
     * 
     * <p>IPv6地址获取原理：</p>
     * <ul>
     *   <li>调用 <code>networkInterface.getInetAddresses()</code> 获取网卡的所有IP地址</li>
     *   <li>使用 <code>instanceof Inet6Address</code> 筛选出IPv6地址</li>
     *   <li>直接返回 <code>Inet6Address</code> 对象，保留完整的地址信息</li>
     *   <li>支持地址验证、网络前缀长度、作用域等高级功能</li>
     * </ul>
     * 
     * <p>Inet6Address对象优势：</p>
     * <ul>
     *   <li>提供完整的IPv6地址信息</li>
     *   <li>支持地址验证和格式检查</li>
     *   <li>可以获取网络前缀长度（子网掩码）</li>
     *   <li>支持地址范围计算和CIDR操作</li>
     *   <li>提供地址类型判断（全球单播、链路本地、唯一本地等）</li>
     *   <li>支持作用域标识符（Scope ID）</li>
     *   <li>支持IPv4映射地址检测</li>
     * </ul>
     * 
     * <p>使用场景：</p>
     * <ul>
     *   <li>需要完整IPv6地址信息的场景</li>
     *   <li>IPv6网络地址计算和CIDR操作</li>
     *   <li>IPv6地址类型判断和分类</li>
     *   <li>IPv6网络配置验证和诊断</li>
     *   <li>高级IPv6网络编程和工具开发</li>
     *   <li>双栈网络环境下的地址管理</li>
     * </ul>
     * 
     * <p>使用示例：</p>
     * <pre>{@code
     * // 获取指定网卡的所有IPv6地址对象
     * NetworkInterface networkInterface = getAllNetworkInterfaces().get(0);
     * List<Inet6Address> ipv6Addresses = NetworkUtils.getIPv6AddressObjects(networkInterface);
     * 
     * if (!ipv6Addresses.isEmpty()) {
     *     System.out.println("网卡 " + networkInterface.getDisplayName() + " 的IPv6地址:");
     *     for (Inet6Address address : ipv6Addresses) {
     *         System.out.println("  " + address.getHostAddress());
     *         
     *         // 检查地址类型
     *         if (address.isLoopbackAddress()) {
     *             System.out.println("    (回环地址)");
     *         } else if (address.isLinkLocalAddress()) {
     *             System.out.println("    (链路本地地址)");
     *         } else if (address.isSiteLocalAddress()) {
     *             System.out.println("    (站点本地地址)");
     *         } else if (address.isMulticastAddress()) {
     *             System.out.println("    (多播地址)");
     *         } else if (address.isAnyLocalAddress()) {
     *             System.out.println("    (任意地址)");
     *         } else {
     *             System.out.println("    (全球单播地址)");
     *         }
     *         
     *         // 检查是否为内网地址
     *         if (isPrivateIPv6Address(address.getHostAddress())) {
     *             System.out.println("    (内网地址)");
     *         } else {
     *             System.out.println("    (公网地址)");
     *         }
     *         
     *         // 检查是否为IPv4映射的IPv6地址
     *         if (isIPv4MappedIPv6Address(address.getHostAddress())) {
     *             String ipv4 = extractIPv4FromMappedIPv6(address.getHostAddress());
     *             System.out.println("    (IPv4映射地址，对应IPv4: " + ipv4 + ")");
     *         }
     *         
     *         // 获取作用域标识符（如果存在）
     *         int scopeId = address.getScopeId();
     *         if (scopeId != 0) {
     *             System.out.println("    作用域ID: " + scopeId);
     *         }
     *     }
     * } else {
     *     System.out.println("该网卡没有配置IPv6地址");
     * }
     * 
     * // 检查系统IPv6支持情况
     * if (isIPv6Supported()) {
     *     System.out.println("系统支持IPv6");
     *     
     *     // 统计所有网卡的IPv6地址对象
     *     List<NetworkInterface> allInterfaces = getAllNetworkInterfaces();
     *     long totalIPv6Count = allInterfaces.stream()
     *         .mapToLong(iface -> getIPv6AddressObjects(iface).size())
     *         .sum();
     *     System.out.println("系统总IPv6地址对象数: " + totalIPv6Count);
     *     
     *     // 分类统计不同类型的IPv6地址
     *     long globalUnicastCount = 0;
     *     long linkLocalCount = 0;
     *     long uniqueLocalCount = 0;
     *     long loopbackCount = 0;
     *     
     *     for (NetworkInterface iface : allInterfaces) {
     *         List<Inet6Address> ipv6List = getIPv6AddressObjects(iface);
     *         for (Inet6Address addr : ipv6List) {
     *             if (addr.isLoopbackAddress()) {
     *                 loopbackCount++;
     *             } else if (addr.isLinkLocalAddress()) {
     *                 linkLocalCount++;
     *             } else if (addr.isSiteLocalAddress()) {
     *                 uniqueLocalCount++;
     *             } else {
     *                 globalUnicastCount++;
     *             }
     *         }
     *     }
     *     
     *     System.out.println("全球单播地址: " + globalUnicastCount);
     *     System.out.println("链路本地地址: " + linkLocalCount);
     *     System.out.println("唯一本地地址: " + uniqueLocalCount);
     *     System.out.println("回环地址: " + loopbackCount);
     * } else {
     *     System.out.println("系统不支持IPv6");
     * }
     * 
     * // IPv6地址范围计算示例
     * for (Inet6Address address : ipv6Addresses) {
     *     String ip = address.getHostAddress();
     *     // 假设子网掩码为64位
     *     IPRange range = getIPRange(ip, 64);
     *     if (range != null) {
     *         System.out.println("地址 " + ip + "/64 的范围:");
     *         System.out.println("  起始IP: " + range.getStartIP());
     *         System.out.println("  结束IP: " + range.getEndIP());
     *     }
     * }
     * }</pre>
     * 
     * @param networkInterface 网络接口对象，不能为null
     * @return 包含所有IPv6地址对象的列表，如果没有IPv6地址则返回空列表
     * @throws IllegalArgumentException 如果网络接口参数为null
     * @throws NetworkException 如果获取网络地址时发生网络异常
     * @see #getIPv6Addresses(NetworkInterface)
     * @see #getIPv4AddressObjects(NetworkInterface)
     * @see #isPrivateIPv6Address(String)
     * @see #isIPv4MappedIPv6Address(String)
     * @see #extractIPv4FromMappedIPv6(String)
     * @see #getIPRange(String, int)
     * @see NetworkInterface#getInetAddresses()
     * @see Inet6Address
     */
    public static List<Inet6Address> getIPv6AddressObjects(NetworkInterface networkInterface) {
        Assert.notNull(networkInterface, "Network interface must not be null");
        
        List<Inet6Address> ipv6Addresses = new ArrayList<>();
        try {
            Enumeration<InetAddress> addresses = networkInterface.getInetAddresses();
            while (addresses.hasMoreElements()) {
                InetAddress address = addresses.nextElement();
                if (address instanceof Inet6Address) {
                    ipv6Addresses.add((Inet6Address) address);
                }
            }
        } catch (Exception e) {
            throw new NetworkException("Failed to get IPv6 address objects for network interface: " + networkInterface.getName(), e);
        }
        
        return ipv6Addresses;
    }

    /**
     * 根据本机主机名获取本机IPv4地址
     * 
     * <p>IPv4地址获取原理：</p>
     * <ul>
     *   <li>使用 <code>InetAddress.getLocalHost()</code> 获取本机主机信息</li>
     *   <li>通过主机名解析获取对应的IP地址</li>
     *   <li>验证返回的地址是否为IPv4类型</li>
     *   <li>如果不是IPv4地址则抛出异常</li>
     * </ul>
     * 
     * <p>方法特点：</p>
     * <ul>
     *   <li>基于主机名解析，符合DNS标准</li>
     *   <li>严格类型检查，确保返回IPv4地址</li>
     *   <li>异常情况下提供明确的错误信息</li>
     *   <li>适用于需要严格IPv4地址验证的场景</li>
     * </ul>
     * 
     * <p>使用场景：</p>
     * <ul>
     *   <li>需要严格IPv4地址验证的应用</li>
     *   <li>基于主机名的网络配置</li>
     *   <li>IPv4专用网络环境</li>
     *   <li>网络协议栈要求IPv4的场景</li>
     * </ul>
     * 
     * <p>使用示例：</p>
     * <pre>{@code
     * try {
     *     // 根据主机名获取IPv4地址
     *     String ipv4Address = NetworkUtils.getLocalIPv4AddressByHostName();
     *     System.out.println("本机IPv4地址: " + ipv4Address);
     *     
     *     // 验证地址类型
     *     if (isValidIPv4Address(ipv4Address)) {
     *         System.out.println("地址格式验证通过");
     *     }
     *     
     *     // 检查是否为内网地址
     *     if (isPrivateIPv4Address(ipv4Address)) {
     *         System.out.println("内网地址");
     *     } else {
     *         System.out.println("公网地址");
     *     }
     *     
     * } catch (NetworkException e) {
     *     System.err.println("获取IPv4地址失败: " + e.getMessage());
     *     // 处理异常情况
     * }
     * 
     * // 在服务器配置中使用
     * try {
     *     String serverIP = getLocalIPv4AddressByHostName();
     *     ServerSocket server = new ServerSocket();
     *     server.bind(new InetSocketAddress(serverIP, 8080));
     *     System.out.println("服务器启动在: " + serverIP + ":8080");
     * } catch (Exception e) {
     *     System.err.println("服务器启动失败: " + e.getMessage());
     * }
     * }</pre>
     * 
     * <p>异常情况：</p>
     * <ul>
     *   <li><code>UnknownHostException</code>：无法解析主机名</li>
     *   <li><code>NetworkException</code>：返回的地址不是IPv4类型</li>
     *   <li><code>IllegalStateException</code>：系统网络配置异常</li>
     * </ul>
     * 
     * @return 本机IPv4地址字符串，如 "192.168.1.100"
     * @throws NetworkException 如果返回的地址不是IPv4类型或网络异常或无法解析本机主机名
     * @see #getLocalIPv6AddressByHostName()
     * @see #isValidIPv4Address(String)
     * @see #isPrivateIPv4Address(String)
     * @see InetAddress#getLocalHost()
     */
    public static String getLocalIPv4AddressByHostName() {
        try {
            InetAddress localHost = InetAddress.getLocalHost();
            
            // 验证是否为IPv4地址
            if (!(localHost instanceof Inet4Address)) {
                String actualAddress = localHost.getHostAddress();
                String actualType = localHost instanceof Inet6Address ? "IPv6" : "Unknown";
                throw new NetworkException(
                    String.format("Expected IPv4 address but got %s address: %s (hostname: %s)", 
                        actualType, actualAddress, localHost.getHostName())
                );
            }
            
            return localHost.getHostAddress();
        } catch (UnknownHostException e) {
            throw new NetworkException("Failed to resolve local hostname", e);
        }
    }

    /**
     * 根据本机主机名获取本机IPv6地址
     * 
     * <p>IPv6地址获取原理：</p>
     * <ul>
     *   <li>使用 <code>InetAddress.getLocalHost()</code> 获取本机主机信息</li>
     *   <li>通过主机名解析获取对应的IP地址</li>
     *   <li>验证返回的地址是否为IPv6类型</li>
     *   <li>如果不是IPv6地址则抛出异常</li>
     * </ul>
     * 
     * <p>方法特点：</p>
     * <ul>
     *   <li>基于主机名解析，符合DNS标准</li>
     *   <li>严格类型检查，确保返回IPv6地址</li>
     *   <li>异常情况下提供明确的错误信息</li>
     *   <li>适用于需要严格IPv6地址验证的场景</li>
     * </ul>
     * 
     * <p>使用场景：</p>
     * <ul>
     *   <li>需要严格IPv6地址验证的应用</li>
     *   <li>基于主机名的IPv6网络配置</li>
     *   <li>IPv6专用网络环境</li>
     *   <li>网络协议栈要求IPv6的场景</li>
     *   <li>双栈网络环境下的IPv6优先配置</li>
     * </ul>
     * 
     * <p>使用示例：</p>
     * <pre>{@code
     * try {
     *     // 根据主机名获取IPv6地址
     *     String ipv6Address = NetworkUtils.getLocalIPv6AddressByHostName();
     *     System.out.println("本机IPv6地址: " + ipv6Address);
     *     
     *     // 验证地址类型
     *     if (isValidIPv6Address(ipv6Address)) {
     *         System.out.println("地址格式验证通过");
     *     }
     *     
     *     // 检查是否为内网地址
     *     if (isPrivateIPv6Address(ipv6Address)) {
     *         System.out.println("内网地址");
     *     } else {
     *         System.out.println("公网地址");
     *     }
     *     
     *     // 检查是否为IPv4映射的IPv6地址
     *     if (isIPv4MappedIPv6Address(ipv6Address)) {
     *         String ipv4 = extractIPv4FromMappedIPv6(ipv6Address);
     *         System.out.println("IPv4映射地址，对应IPv4: " + ipv4);
     *     }
     *     
     * } catch (NetworkException e) {
     *     System.err.println("获取IPv6地址失败: " + e.getMessage());
     *     // 处理异常情况
     * }
     * 
     * // 在IPv6服务器配置中使用
     * try {
     *     String serverIP = getLocalIPv6AddressByHostName();
     *     ServerSocket server = new ServerSocket();
     *     server.bind(new InetSocketAddress(serverIP, 8080));
     *     System.out.println("IPv6服务器启动在: [" + serverIP + "]:8080");
     * } catch (Exception e) {
     *     System.err.println("IPv6服务器启动失败: " + e.getMessage());
     * }
     * 
     * // 检查系统IPv6支持
     * if (isIPv6Supported()) {
     *     try {
     *         String ipv6 = getLocalIPv6AddressByHostName();
     *         System.out.println("系统支持IPv6，地址: " + ipv6);
     *     } catch (Exception e) {
     *         System.out.println("系统支持IPv6但无法通过主机名获取地址");
     *     }
     * } else {
     *     System.out.println("系统不支持IPv6");
     * }
     * }</pre>
     * 
     * <p>异常情况：</p>
     * <ul>
     *   <li><code>UnknownHostException</code>：无法解析主机名</li>
     *   <li><code>NetworkException</code>：返回的地址不是IPv6类型</li>
     *   <li><code>IllegalStateException</code>：系统网络配置异常</li>
     * </ul>
     * 
     * <p>注意事项：</p>
     * <ul>
     *   <li>确保系统已启用IPv6支持</li>
     *   <li>检查网络配置是否支持IPv6</li>
     *   <li>某些网络环境可能只支持IPv4</li>
     *   <li>建议在使用前调用 <code>isIPv6Supported()</code> 检查</li>
     * </ul>
     * 
     * @return 本机IPv6地址字符串，如 "2001:db8::1"
     * @throws NetworkException 如果返回的地址不是IPv6类型或网络异常或无法解析本机主机名
     * @see #getLocalIPv4AddressByHostName()
     * @see #isValidIPv6Address(String)
     * @see #isPrivateIPv6Address(String)
     * @see #isIPv6Supported()
     * @see #isIPv4MappedIPv6Address(String)
     * @see InetAddress#getLocalHost()
     */
    public static String getLocalIPv6AddressByHostName() {
        try {
            InetAddress localHost = InetAddress.getLocalHost();
            
            // 验证是否为IPv6地址
            if (!(localHost instanceof Inet6Address)) {
                String actualAddress = localHost.getHostAddress();
                String actualType = localHost instanceof Inet4Address ? "IPv4" : "Unknown";
                throw new NetworkException(
                    String.format("Expected IPv6 address but got %s address: %s (hostname: %s)", 
                        actualType, actualAddress, localHost.getHostName())
                );
            }
            
            return localHost.getHostAddress();
        } catch (UnknownHostException e) {
            throw new NetworkException("Failed to resolve local hostname", e);
        }
    }

    /**
     * 根据本机主机名获取本机IP地址（不限制IP类型）
     * 
     * <p>IP地址获取原理：</p>
     * <ul>
     *   <li>使用 <code>InetAddress.getLocalHost()</code> 获取本机主机信息</li>
     *   <li>通过主机名解析获取对应的IP地址</li>
     *   <li>支持IPv4和IPv6地址类型</li>
     *   <li>返回系统解析到的任意类型IP地址</li>
     * </ul>
     * 
     * <p>方法特点：</p>
     * <ul>
     *   <li>基于主机名解析，符合DNS标准</li>
     *   <li>不限制IP地址类型，自动适应系统配置</li>
     *   <li>适用于需要获取本机IP地址但不关心具体类型的场景</li>
     *   <li>兼容IPv4和IPv6双栈网络环境</li>
     * </ul>
     * 
     * <p>使用场景：</p>
     * <ul>
     *   <li>需要获取本机IP地址但不关心类型的应用</li>
     *   <li>双栈网络环境下的通用IP地址获取</li>
     *   <li>网络配置和诊断工具</li>
     *   <li>服务器地址配置（支持IPv4和IPv6）</li>
     *   <li>网络通信应用的地址获取</li>
     * </ul>
     * 
     * <p>使用示例：</p>
     * <pre>{@code
     * try {
     *     // 根据主机名获取本机IP地址（不限制类型）
     *     String localIP = NetworkUtils.getLocalIPAddressByHostName();
     *     System.out.println("本机IP地址: " + localIP);
     *     
     *     // 检查IP地址类型
     *     if (isValidIPv4Address(localIP)) {
     *         System.out.println("IPv4地址");
     *         
     *         // 检查是否为内网地址
     *         if (isPrivateIPv4Address(localIP)) {
     *             System.out.println("内网IPv4地址");
     *         } else {
     *             System.out.println("公网IPv4地址");
     *         }
     *     } else if (isValidIPv6Address(localIP)) {
     *         System.out.println("IPv6地址");
     *         
     *         // 检查是否为内网地址
     *         if (isPrivateIPv6Address(localIP)) {
     *             System.out.println("内网IPv6地址");
     *         } else {
     *             System.out.println("公网IPv6地址");
     *         }
     *         
     *         // 检查是否为IPv4映射的IPv6地址
     *         if (isIPv4MappedIPv6Address(localIP)) {
     *             String ipv4 = extractIPv4FromMappedIPv6(localIP);
     *             System.out.println("IPv4映射地址，对应IPv4: " + ipv4);
     *         }
     *     }
     *     
     * } catch (NetworkException e) {
     *     System.err.println("获取本机IP地址失败: " + e.getMessage());
     *     // 处理异常情况
     * }
     * 
     * // 在服务器配置中使用（支持IPv4和IPv6）
     * try {
     *     String serverIP = getLocalIPAddressByHostName();
     *     ServerSocket server = new ServerSocket();
     *     
     *     if (isValidIPv6Address(serverIP)) {
     *         // IPv6地址需要用方括号包围
     *         server.bind(new InetSocketAddress("[" + serverIP + "]", 8080));
     *         System.out.println("IPv6服务器启动在: [" + serverIP + "]:8080");
     *     } else {
     *         // IPv4地址直接使用
     *         server.bind(new InetSocketAddress(serverIP, 8080));
     *         System.out.println("IPv4服务器启动在: " + serverIP + ":8080");
     *     }
     * } catch (Exception e) {
     *     System.err.println("服务器启动失败: " + e.getMessage());
     * }
     * 
     * // 网络诊断示例
     * try {
     *     String localIP = getLocalIPAddressByHostName();
     *     System.out.println("本机IP地址: " + localIP);
     *     
     *     // 检查网络连通性
     *     if (hasInternetConnection()) {
     *         System.out.println("网络连接正常");
     *     } else {
     *         System.out.println("网络连接异常");
     *     }
     *     
     *     // 检查端口开放情况
     *     if (isPortOpen(localIP, 8080)) {
     *         System.out.println("端口8080已开放");
     *     } else {
     *         System.out.println("端口8080未开放");
     *     }
     *     
     * } catch (NetworkException e) {
     *     System.err.println("网络诊断失败: " + e.getMessage());
     * }
     * }</pre>
     * 
     * <p>异常情况：</p>
     * <ul>
     *   <li><code>NetworkException</code>：网络异常或无法解析主机名</li>
     *   <li><code>IllegalStateException</code>：系统网络配置异常</li>
     * </ul>
     * 
     * <p>注意事项：</p>
     * <ul>
     *   <li>返回的IP地址类型取决于系统网络配置</li>
     *   <li>在双栈网络环境下，可能优先返回IPv6地址</li>
     *   <li>某些网络环境可能只支持IPv4</li>
     *   <li>建议在使用前检查IP地址类型</li>
     * </ul>
     * 
     * @return 本机IP地址字符串，可能是IPv4或IPv6格式
     * @throws NetworkException 如果网络异常或无法解析主机名
     * @see #getLocalIPv4AddressByHostName()
     * @see #getLocalIPv6AddressByHostName()
     * @see #isValidIPv4Address(String)
     * @see #isValidIPv6Address(String)
     * @see #isPrivateIPv4Address(String)
     * @see #isPrivateIPv6Address(String)
     * @see InetAddress#getLocalHost()
     */
    public static String getLocalIPAddressByHostName() {
        try {
            return InetAddress.getLocalHost().getHostAddress();
        } catch (UnknownHostException e) {
            throw new NetworkException("Failed to resolve local hostname", e);
        }
    }

    /**
     * 检测IP地址是否为本地回环地址
     * 
     * <p>回环地址检测原理：</p>
     * <ul>
     *   <li>IPv4回环地址：127.0.0.0/8 网段（127.0.0.1 是最常用的回环地址）</li>
     *   <li>IPv6回环地址：::1（IPv6的唯一回环地址）</li>
     *   <li>自动识别IP地址类型并进行相应的检测</li>
     * </ul>
     * 
     * <p>回环地址特征：</p>
     * <ul>
     *   <li>用于本机内部通信，不会发送到网络</li>
     *   <li>通常用于本地服务测试和开发</li>
     *   <li>在网络安全中，回环地址被认为是安全的</li>
     *   <li>回环地址无法从外部网络访问</li>
     * </ul>
     * 
     * <p>使用场景：</p>
     * <ul>
     *   <li>网络配置验证</li>
     *   <li>安全策略实施</li>
     *   <li>本地服务检测</li>
     *   <li>网络故障诊断</li>
     *   <li>防火墙规则配置</li>
     * </ul>
     * 
     * <p>使用示例：</p>
     * <pre>{@code
     * // 检测IPv4回环地址
     * boolean isLoopback1 = NetworkUtils.isLoopbackAddress("127.0.0.1");
     * System.out.println("127.0.0.1 是回环地址: " + isLoopback1); // true
     * 
     * boolean isLoopback2 = NetworkUtils.isLoopbackAddress("127.0.0.100");
     * System.out.println("127.0.0.100 是回环地址: " + isLoopback2); // true
     * 
     * boolean isLoopback3 = NetworkUtils.isLoopbackAddress("192.168.1.1");
     * System.out.println("192.168.1.1 是回环地址: " + isLoopback3); // false
     * 
     * // 检测IPv6回环地址
     * boolean isLoopback4 = NetworkUtils.isLoopbackAddress("::1");
     * System.out.println("::1 是回环地址: " + isLoopback4); // true
     * 
     * boolean isLoopback5 = NetworkUtils.isLoopbackAddress("2001:db8::1");
     * System.out.println("2001:db8::1 是回环地址: " + isLoopback5); // false
     * 
     * // 批量检测IP地址
     * String[] testIPs = {
     *     "127.0.0.1",      // IPv4回环
     *     "127.0.0.100",    // IPv4回环
     *     "192.168.1.1",    // IPv4非回环
     *     "10.0.0.1",       // IPv4非回环
     *     "::1",            // IPv6回环
     *     "2001:db8::1",    // IPv6非回环
     *     "fe80::1",        // IPv6链路本地
     *     "fc00::1"         // IPv6唯一本地
     * };
     * 
     * for (String ip : testIPs) {
     *     boolean isLoopback = isLoopbackAddress(ip);
     *     String type = isValidIPv4Address(ip) ? "IPv4" : "IPv6";
     *     String status = isLoopback ? "回环地址" : "非回环地址";
     *     System.out.printf("%s (%s): %s%n", ip, type, status);
     * }
     * 
     * // 在网络安全检查中使用
     * String clientIP = "127.0.0.1";
     * if (isLoopbackAddress(clientIP)) {
     *     System.out.println("客户端来自本地回环地址，允许访问");
     *     // 执行本地访问逻辑
     * } else {
     *     System.out.println("客户端来自外部网络，需要验证权限");
     *     // 执行权限验证逻辑
     * }
     * 
     * // 在服务器配置中使用
     * String serverIP = "127.0.0.1";
     * if (isLoopbackAddress(serverIP)) {
     *     System.out.println("服务器配置为仅本地访问");
     *     // 配置为仅本地访问
     * } else {
     *     System.out.println("服务器配置为网络访问");
     *     // 配置为网络访问
     * }
     * }</pre>
     * 
     * <p>技术细节：</p>
     * <ul>
     *   <li>IPv4回环地址检测：检查IP是否在127.0.0.0/8网段内</li>
     *   <li>IPv6回环地址检测：检查IP是否等于::1</li>
     *   <li>自动处理IP地址格式验证</li>
     *   <li>支持标准IPv4和IPv6地址格式</li>
     * </ul>
     * 
     * @param ip 要检测的IP地址，支持IPv4和IPv6格式
     * @return true表示是回环地址，false表示不是回环地址
     * @see #isValidIPv4Address(String)
     * @see #isValidIPv6Address(String)
     * @see #isPrivateIPv4Address(String)
     * @see #isPrivateIPv6Address(String)
     * @see #LOCAL_LOOPBACK_V4_IP
     */
    public static boolean isLoopbackAddress(String ip) {
        Assert.notBlank(ip , "IP address cannot be null or empty");
        
        String trimmedIP = ip.trim();
        
        // 检测IPv4回环地址
        if (isValidIPv4Address(trimmedIP)) {
            return isIPv4LoopbackAddress(trimmedIP);
        }
        
        // 检测IPv6回环地址
        if (isValidIPv6Address(trimmedIP)) {
            return isIPv6LoopbackAddress(trimmedIP);
        }
        
        return false;
    }

    /**
     * 检测IPv4地址是否为回环地址。
     *
     * <p>回环地址说明：</p>
     * <ul>
     *   <li><strong>地址范围</strong>：127.0.0.0 - 127.255.255.255</li>
     *   <li><strong>子网掩码</strong>：255.0.0.0 (/8)</li>
     *   <li><strong>最常用地址</strong>：127.0.0.1（localhost）</li>
     *   <li><strong>用途</strong>：本机内部通信、本地服务测试、开发调试</li>
     * </ul>
     *
     * <p>回环地址特征：</p>
     * <ul>
     *   <li>数据包不会发送到网络，只在本地回环</li>
     *   <li>用于本机内部进程间通信</li>
     *   <li>在网络安全中，回环地址被认为是安全的</li>
     *   <li>回环地址无法从外部网络访问</li>
     *   <li>支持TCP、UDP等所有网络协议</li>
     * </ul>
     *
     * <p>检测原理：</p>
     * <ol>
     *   <li>首先验证IPv4地址格式的有效性</li>
     *   <li>解析地址的四个八位字节</li>
     *   <li>检查第一个八位字节是否为127</li>
     *   <li>其他三个八位字节可以是任意值（0-255）</li>
     *   <li>返回布尔值表示是否为回环地址</li>
     * </ol>
     *
     * <p>使用场景：</p>
     * <ul>
     *   <li>本地服务配置和测试</li>
     *   <li>开发环境下的服务调试</li>
     *   <li>网络安全策略实施</li>
     *   <li>服务器绑定地址验证</li>
     *   <li>网络配置验证</li>
     *   <li>防火墙规则配置</li>
     * </ul>
     *
     * <p>使用示例：</p>
     * <pre>{@code
     * // 检测回环地址
     * boolean isLoopback1 = NetworkUtils.isIPv4LoopbackAddress("127.0.0.1");
     * System.out.println("127.0.0.1 是回环地址: " + isLoopback1); // true
     *
     * boolean isLoopback2 = NetworkUtils.isIPv4LoopbackAddress("127.255.255.254");
     * System.out.println("127.255.255.254 是回环地址: " + isLoopback2); // true
     *
     * boolean isLoopback3 = NetworkUtils.isIPv4LoopbackAddress("128.0.0.1");
     * System.out.println("128.0.0.1 是回环地址: " + isLoopback3); // false
     *
     * // 批量检测IP地址
     * String[] testIPs = {
     *     "127.0.0.1",      // 回环地址
     *     "127.0.0.100",    // 回环地址
     *     "127.255.255.254", // 回环地址
     *     "192.168.1.1",    // 内网地址
     *     "8.8.8.8"         // 公网地址
     * };
     *
     * for (String ip : testIPs) {
     *     if (isIPv4LoopbackAddress(ip)) {
     *         System.out.println(ip + " 是回环地址");
     *     } else {
     *         System.out.println(ip + " 不是回环地址");
     *     }
     * }
     *
     * // 在服务器配置中使用
     * String serverIP = "127.0.0.1";
     * if (isIPv4LoopbackAddress(serverIP)) {
     *     System.out.println("服务器配置为仅本地访问");
     *     // 配置为仅本地访问
     * } else {
     *     System.out.println("服务器配置为网络访问");
     *     // 配置为网络访问
     * }
     *
     * // 在网络安全检查中使用
     * String clientIP = "127.0.0.1";
     * if (isIPv4LoopbackAddress(clientIP)) {
     *     System.out.println("客户端来自本地回环地址，允许访问");
     *     // 执行本地访问逻辑
     * } else {
     *     System.out.println("客户端来自外部网络，需要验证权限");
     *     // 执行权限验证逻辑
     * }
     * }</pre>
     *
     * <p>相关标准：</p>
     * <ul>
     *   <li><a href="https://tools.ietf.org/html/rfc5735">RFC 5735</a> - 特殊用途IPv4地址</li>
     *   <li><a href="https://tools.ietf.org/html/rfc6890">RFC 6890</a> - 特殊用途地址注册表</li>
     *   <li><a href="https://tools.ietf.org/html/rfc1122">RFC 1122</a> - 主机要求规范</li>
     * </ul>
     *
     * <p>注意事项：</p>
     * <ul>
     *   <li>此方法仅适用于IPv4地址，IPv6回环地址请使用 {@link #isIPv6LoopbackAddress(String)}</li>
     *   <li>回环地址（127.0.0.0/8）也被认为是内网地址</li>
     *   <li>某些系统可能只支持127.0.0.1，其他127.x.x.x地址可能不可用</li>
     *   <li>在容器化环境中，回环地址的行为可能有所不同</li>
     *   <li>建议在网络安全策略中结合其他验证方法使用</li>
     * </ul>
     *
     * @param ip 要检测的IPv4地址，不能为null或空字符串
     * @return {@code true} 表示是回环地址，{@code false} 表示不是回环地址
     * @throws IllegalArgumentException 如果IPv4地址格式无效
     * @see #isIPv6LoopbackAddress(String)
     * @see #isLoopbackAddress(String)
     * @see #isPrivateIPv4Address(String)
     * @see #isValidIPv4Address(String)
     * @since 1.0
     */
    public static boolean isIPv4LoopbackAddress(String ip) {
        if (!isValidIPv4Address(ip)) {
            return false;
        }

        String[] parts = ip.split("\\.");
        int firstOctet = Integer.parseInt(parts[0]);

        // 127.0.0.0 - 127.255.255.255
        return firstOctet == 127;
    }
    
    /**
     * 检测IPv6地址是否为回环地址
     * 
     * <p>IPv6回环地址：::1</p>
     * <ul>
     *   <li>唯一的标准IPv6回环地址</li>
     *   <li>等同于IPv4的127.0.0.1</li>
     *   <li>用于本机内部通信</li>
     * </ul>
     * 
     * @param ip IPv6地址字符串
     * @return true表示是IPv6回环地址
     */
    public static boolean isIPv6LoopbackAddress(String ip) {
        return "::1".equals(ip);
    }

    /**
     * 将IPv4地址转换为IPv4映射的IPv6地址
     * 
     * <p>IPv4映射IPv6地址说明：</p>
     * <ul>
     *   <li>格式：::ffff:IPv4地址</li>
     *   <li>用于在IPv6环境中表示IPv4地址</li>
     *   <li>标准格式：::ffff:192.168.1.1</li>
     *   <li>主要用于双栈网络环境</li>
     * </ul>
     * 
     * <p>转换原理：</p>
     * <ul>
     *   <li>在IPv6地址的前80位填充0</li>
     *   <li>第81-96位设置为0xFFFF</li>
     *   <li>最后32位使用IPv4地址</li>
     *   <li>结果：0000:0000:0000:0000:0000:FFFF:IPv4</li>
     * </ul>
     * 
     * <p>使用场景：</p>
     * <ul>
     *   <li>IPv6网络环境下的IPv4兼容性</li>
     *   <li>双栈应用程序开发</li>
     *   <li>网络协议转换</li>
     *   <li>IPv6迁移过程中的地址映射</li>
     * </ul>
     * 
     * <p>使用示例：</p>
     * <pre>{@code
     * // 基本转换
     * String ipv6 = NetworkUtils.convertIPv4ToIPv6("192.168.1.1");
     * System.out.println("IPv6映射地址: " + ipv6); // ::ffff:192.168.1.1
     * 
     * // 转换内网地址
     * String privateIPv6 = NetworkUtils.convertIPv4ToIPv6("10.0.0.1");
     * System.out.println("内网IPv6映射: " + privateIPv6); // ::ffff:10.0.0.1
     * 
     * // 转换公网地址
     * String publicIPv6 = NetworkUtils.convertIPv4ToIPv6("8.8.8.8");
     * System.out.println("公网IPv6映射: " + publicIPv6); // ::ffff:8.8.8.8
     * 
     * // 批量转换
     * String[] ipv4Addresses = {"192.168.1.1", "10.0.0.1", "172.16.0.1"};
     * for (String ipv4 : ipv4Addresses) {
     *     String ipv6 = convertIPv4ToIPv6(ipv4);
     *     System.out.println(ipv4 + " -> " + ipv6);
     * }
     * 
     * // 在双栈应用中使用
     * String serverIPv4 = "192.168.1.100";
     * String serverIPv6 = convertIPv4ToIPv6(serverIPv4);
     * 
     * // 创建IPv6 Socket连接
     * try {
     *     InetAddress ipv6Address = InetAddress.getByName(serverIPv6);
     *     Socket socket = new Socket(ipv6Address, 8080);
     *     System.out.println("通过IPv6映射地址连接到IPv4服务器");
     *     socket.close();
     * } catch (Exception e) {
     *     e.printStackTrace();
     * }
     * }</pre>
     * 
     * <p>注意事项：</p>
     * <ul>
     *   <li>输入的IPv4地址必须是有效格式</li>
     *   <li>转换后的地址仍然是IPv4地址，只是用IPv6格式表示</li>
     *   <li>某些IPv6网络可能不支持IPv4映射地址</li>
     *   <li>建议在双栈环境中使用</li>
     * </ul>
     * 
     * @param ipv4 要转换的IPv4地址，如 "192.168.1.1"
     * @return IPv4映射的IPv6地址，如 "::ffff:192.168.1.1"
     * @throws IllegalArgumentException 如果IPv4地址格式无效
     * @see #convertIPv6ToIPv4(String)
     * @see #isIPv4MappedIPv6Address(String)
     * @see #extractIPv4FromMappedIPv6(String)
     * @see #isValidIPv4Address(String)
     */
    public static String convertIPv4ToIPv6(String ipv4) {
        Assert.notBlank(ipv4, "IPv4 address cannot be null or empty");
        Assert.isFalse(isValidIPv4Address(ipv4) , "Invalid IPv4 address format: " + ipv4);
        return "::ffff:" + ipv4;
    }

    /**
     * 将IPv6地址转换为IPv4地址（仅支持IPv4映射的IPv6地址）
     * 
     * @param ipv6 IPv6地址，必须是IPv4映射格式，如 "::ffff:192.168.1.1"
     * @return 提取的IPv4地址，如 "192.168.1.1"
     * @throws IllegalArgumentException 如果不是IPv4映射的IPv6地址或地址格式无效
     */
    public static String convertIPv6ToIPv4(String ipv6) {
        Assert.notBlank(ipv6, "IPv6 address cannot be null or empty");
        Assert.isFalse(isValidIPv6Address(ipv6) , "Not an IPv6 address: " + ipv6);
        Assert.isFalse(isIPv4MappedIPv6Address(ipv6) , "Not an IPv4-mapped IPv6 address: " + ipv6);
        return extractIPv4FromMappedIPv6(ipv6);
    }

    /**
     * 标准化IP地址格式
     * 
     * @param ip 要标准化的IP地址，支持IPv4和IPv6格式
     * @return 标准化后的IP地址
     * @throws IllegalArgumentException 如果IP地址格式无效
     */
    public static String normalizeIPAddress(String ip) {
        Assert.notBlank(ip, "IP address cannot be null or empty");
        
        String trimmedIP = ip.trim();
        
        // 检测并标准化IPv4地址
        if (isValidIPv4Address(trimmedIP)) {
            return normalizeIPv4Address(trimmedIP);
        }
        
        // 检测并标准化IPv6地址
        if (isValidIPv6Address(trimmedIP)) {
            return normalizeIPv6Address(trimmedIP);
        }
        
        throw new IllegalArgumentException("Invalid IP address format: " + ip);
    }
    
    /**
     * 标准化IPv4地址（内部方法）
     * 
     * @param ip IPv4地址字符串
     * @return 标准化后的IPv4地址
     */
    private static String normalizeIPv4Address(String ip) {
        String[] parts = ip.split("\\.");
        StringBuilder normalized = new StringBuilder();
        
        for (int i = 0; i < parts.length; i++) {
            // 移除前导零，但保留单个0
            int octet = Integer.parseInt(parts[i]);
            normalized.append(octet);
            
            if (i < parts.length - 1) {
                normalized.append(".");
            }
        }
        
        return normalized.toString();
    }
    
    /**
     * 标准化IPv6地址（内部方法）
     * 
     * @param ip IPv6地址字符串
     * @return 标准化后的IPv6地址
     */
    private static String normalizeIPv6Address(String ip) {
        try {
            InetAddress address = InetAddress.getByName(ip);
            if (address instanceof Inet6Address) {
                return address.getHostAddress().toLowerCase();
            }
        } catch (Exception e) {
            // 如果解析失败，返回原地址
        }
        
        // 如果无法解析，进行基本的标准化
        return ip.toLowerCase().trim();
    }

    /**
     * 解析域名获取IP地址列表
     * 
     * @param domain 要解析的域名，如 "www.google.com"
     * @return 域名对应的IP地址列表
     * @throws IllegalArgumentException 如果域名为空或格式无效
     * @throws NetworkException 如果DNS解析失败
     */
    public static List<String> resolveDomain(String domain) {
        Assert.notBlank(domain, "Domain cannot be null or empty");

        Assert.isFalse(isValidDomain(domain) , "Invalid domain format: " + domain);
        try {
            InetAddress[] addresses = InetAddress.getAllByName(domain);
            List<String> ipList = new ArrayList<>();
            
            for (InetAddress address : addresses) {
                ipList.add(address.getHostAddress());
            }
            
            return ipList;
        } catch (UnknownHostException e) {
            throw new NetworkException("Failed to resolve domain: " + domain, e);
        }
    }

    /**
     * 反向DNS查询，将IP地址解析为主机名
     * 
     * @param ip 要反向查询的IP地址
     * @return IP地址对应的主机名，如果无法解析则返回IP地址本身
     * @throws IllegalArgumentException 如果IP地址格式无效
     * @throws NetworkException 如果反向DNS查询失败
     */
    public static String reverseLookup(String ip) {
        Assert.notBlank(ip, "IP address cannot be null or empty");
        Assert.isFalse(isValidIPAddress(ip) , "Invalid IP address format: " + ip);
        
        try {
            InetAddress address = InetAddress.getByName(ip);
            String hostname = address.getHostName();
            
            // 如果主机名与IP地址相同，说明反向解析失败，返回IP地址
            return hostname.equals(ip) ? ip : hostname;
        } catch (UnknownHostException e) {
            throw new NetworkException("Failed to perform reverse lookup for IP: " + ip, e);
        }
    }

    /**
     * 通过 ip-api.com 接口查询IP地址的地理位置信息
     *
     * <p>该接口提供免费的IP地理位置查询服务，每分钟限制45次请求。</p>
     *
     * <p>接口地址：<a href="http://ip-api.com/json/{ip}">http://ip-api.com/json/{ip}</a></p>
     *
     * <p>使用示例：</p>
     * <pre>{@code
     * // 查询指定IP地址的地理位置信息
     * IPGeolocation geo = NetworkUtils.getIPGeolocation("219.144.252.40");
     * if (geo.isSuccess()) {
     *     System.out.println("国家: " + geo.getCountry());
     *     System.out.println("城市: " + geo.getCity());
     *     System.out.println("运营商: " + geo.getIsp());
     *     System.out.println("ASN: " + geo.getAs());
     *     System.out.println("时区: " + geo.getTimezone());
     *     System.out.println("坐标: " + geo.getCoordinates());
     * } else {
     *     System.out.println("查询失败: " + geo.getMessage());
     * }
     * }</pre>
     *
     * <p>返回的地理位置信息包括：</p>
     * <ul>
     *   <li><strong>基本信息</strong>：国家、省份、城市、地区、邮政编码</li>
     *   <li><strong>网络信息</strong>：运营商(ISP)、组织名称、ASN、AS名称</li>
     *   <li><strong>地理位置</strong>：纬度、经度、时区、UTC偏移量</li>
     *   <li><strong>网络特征</strong>：是否为移动网络、代理服务器、托管服务</li>
     *   <li><strong>其他信息</strong>：大陆、货币、反向DNS解析</li>
     * </ul>
     *
     * <p>超时设置：</p>
     * <ul>
     *   <li><strong>连接超时</strong>：5秒（5000毫秒）</li>
     *   <li><strong>读取超时</strong>：10秒（10000毫秒）</li>
     * </ul>
     *
     * <p>注意事项：</p>
     * <ul>
     *   <li>该接口为免费服务，有请求频率限制（每分钟45次）</li>
     *   <li>建议在生产环境中使用付费服务或本地数据库</li>
     *   <li>网络异常时会返回包含错误信息的IPGeolocation对象</li>
     *   <li>某些IP地址可能返回不完整的信息</li>
     *   <li>如需自定义超时时间，请使用 {@link #getIPGeolocation(String, int, int)} 方法</li>
     * </ul>
     *
     * <p>错误处理：</p>
     * <ul>
     *   <li>IP地址格式无效时抛出 {@link IllegalArgumentException}</li>
     *   <li>网络异常时返回status为"fail"的IPGeolocation对象</li>
     *   <li>可通过 {@link IPGeolocation#isSuccess()} 方法判断查询是否成功</li>
     *   <li>失败原因可通过 {@link IPGeolocation#getMessage()} 方法获取</li>
     * </ul>
     *
     * @param ipAddress 要查询的IP地址，支持IPv4和IPv6格式
     * @return IP地理位置信息对象，查询失败时status字段为"fail"
     * @throws IllegalArgumentException 如果IP地址格式无效或为空
     * @see #getIPGeolocation(String, int, int)
     * @see IPGeolocation
     * @since 1.0
     */
    public static IPGeolocation getIPGeolocation(String ipAddress) {
        return getIPGeolocation(ipAddress, 5000, 10000);
    }

    /**
     * 通过 ip-api.com 接口查询IP地址的地理位置信息（支持自定义超时时间）
     *
     * <p>该接口提供免费的IP地理位置查询服务，每分钟限制45次请求。</p>
     *
     * <p>接口地址：<a href="http://ip-api.com/json/{ip}">http://ip-api.com/json/{ip}</a></p>
     *
     * <p>使用示例：</p>
     * <pre>{@code
     * // 使用默认超时时间查询
     * IPGeolocation geo1 = NetworkUtils.getIPGeolocation("219.144.252.40");
     *
     * // 使用自定义超时时间查询（快速查询）
     * IPGeolocation geo2 = NetworkUtils.getIPGeolocation("219.144.252.40", 5000, 8000);
     *
     * // 使用自定义超时时间查询（慢速网络环境）
     * IPGeolocation geo3 = NetworkUtils.getIPGeolocation("219.144.252.40", 30000, 45000);
     *
     * if (geo1.isSuccess()) {
     *     System.out.println("国家: " + geo1.getCountry());
     *     System.out.println("城市: " + geo1.getCity());
     *     System.out.println("运营商: " + geo1.getIsp());
     *     System.out.println("ASN: " + geo1.getAs());
     * }
     * }</pre>
     *
     * <p>超时时间说明：</p>
     * <ul>
     *   <li><strong>连接超时</strong>：建立TCP连接的最大等待时间</li>
     *   <li><strong>读取超时</strong>：从连接读取数据的最大等待时间</li>
     *   <li><strong>建议值</strong>：
     *     <ul>
     *       <li>快速网络：连接超时 3-5秒，读取超时 5-8秒</li>
     *       <li>普通网络：连接超时 10-15秒，读取超时 15-20秒</li>
     *       <li>慢速网络：连接超时 20-30秒，读取超时 30-45秒</li>
     *     </ul>
     *   </li>
     * </ul>
     *
     * <p>注意事项：</p>
     * <ul>
     *   <li>该接口为免费服务，有请求频率限制</li>
     *   <li>建议在生产环境中使用付费服务或本地数据库</li>
     *   <li>网络异常时会返回包含错误信息的IPGeolocation对象</li>
     *   <li>某些IP地址可能返回不完整的信息</li>
     *   <li>超时时间过短可能导致查询失败，过长可能影响用户体验</li>
     * </ul>
     *
     * @param ipAddress 要查询的IP地址
     * @param connectTimeoutMillis 连接超时时间（毫秒），建议值：5000-30000
     * @param readTimeoutMillis 读取超时时间（毫秒），建议值：8000-45000
     * @return IP地理位置信息对象，查询失败时status字段为"fail"
     * @throws IllegalArgumentException 如果IP地址格式无效或超时时间不合理
     * @since 1.0
     */
    public static IPGeolocation getIPGeolocation(String ipAddress, int connectTimeoutMillis, int readTimeoutMillis) {
        // 验证IP地址格式
        Assert.isTrue(isValidIPAddress(ipAddress), "Invalid IP address: " + ipAddress);

        // 验证超时时间参数
        Assert.isFalse(connectTimeoutMillis <= 0 || readTimeoutMillis <= 0, "The timeout parameter cannot be negative");

        try {
            // 构建API请求URL
            String apiUrl = "http://ip-api.com/json/" + ipAddress + "?fields=status,message,continent,continentCode,country,countryCode,region,regionName,city,district,zip,lat,lon,timezone,offset,currency,isp,org,as,asname,reverse,mobile,proxy,hosting,query";

            // 创建HTTP连接
            URL url = new URL(apiUrl);
            HttpURLConnection connection = (HttpURLConnection) url.openConnection();
            connection.setRequestMethod("GET");
            connection.setConnectTimeout(connectTimeoutMillis);
            connection.setReadTimeout(readTimeoutMillis);
            connection.setRequestProperty("Accept", "application/json");
            connection.setRequestProperty("Accept-Charset", "UTF-8");

            // 发送请求并获取响应
            int responseCode = connection.getResponseCode();
            if (responseCode == HttpURLConnection.HTTP_OK) {
                // 读取响应数据
                StringBuilder response = new StringBuilder();
                try (BufferedReader reader = new BufferedReader(
                        new InputStreamReader(connection.getInputStream(), StandardCharsets.UTF_8))) {
                    String line;
                    while ((line = reader.readLine()) != null) {
                        response.append(line);
                    }
                }

                // 解析JSON响应
                return parseIPGeolocationResponse(response.toString());

            } else {
                // HTTP错误响应
                IPGeolocation errorGeo = new IPGeolocation(ipAddress);
                errorGeo.setStatus("fail");
                errorGeo.setMessage("HTTP Error: " + responseCode + " - " + connection.getResponseMessage());
                return errorGeo;
            }

        } catch (SocketTimeoutException e) {
            // 超时异常处理
            IPGeolocation errorGeo = new IPGeolocation(ipAddress);
            errorGeo.setStatus("fail");
            if (e.getMessage().contains("connect timed out")) {
                errorGeo.setMessage("Connect timeout: " + connectTimeoutMillis + "ms");
            } else if (e.getMessage().contains("Read timeout")) {
                errorGeo.setMessage("Read timeout: " + readTimeoutMillis + "ms");
            } else {
                errorGeo.setMessage("Network timeout: " + e.getMessage());
            }
            return errorGeo;

        } catch (Exception e) {
            // 其他网络异常或其他错误
            IPGeolocation errorGeo = new IPGeolocation(ipAddress);
            errorGeo.setStatus("fail");
            errorGeo.setMessage("Query Failed: " + e.getMessage());
            return errorGeo;
        }
    }

    /**
     * 解析IP地理位置API的JSON响应
     *
     * @param jsonResponse JSON响应字符串
     * @return 解析后的IPGeolocation对象
     */
    private static IPGeolocation parseIPGeolocationResponse(String jsonResponse) {
        try {
            // 使用简单的字符串解析，避免引入额外的JSON库依赖
            IPGeolocation geo = new IPGeolocation();

            // 解析status字段
            if (jsonResponse.contains("\"status\":\"success\"")) {
                geo.setStatus("success");
            } else if (jsonResponse.contains("\"status\":\"fail\"")) {
                geo.setStatus("fail");
            }

            // 解析其他字段
            geo.setCountry(extractJsonValue(jsonResponse, "country"));
            geo.setCountryCode(extractJsonValue(jsonResponse, "countryCode"));
            geo.setRegion(extractJsonValue(jsonResponse, "region"));
            geo.setRegionName(extractJsonValue(jsonResponse, "regionName"));
            geo.setCity(extractJsonValue(jsonResponse, "city"));
            geo.setDistrict(extractJsonValue(jsonResponse, "district"));
            geo.setZip(extractJsonValue(jsonResponse, "zip"));
            geo.setTimezone(extractJsonValue(jsonResponse, "timezone"));
            geo.setIsp(extractJsonValue(jsonResponse, "isp"));
            geo.setOrg(extractJsonValue(jsonResponse, "org"));
            geo.setAs(extractJsonValue(jsonResponse, "as"));
            geo.setAsname(extractJsonValue(jsonResponse, "asname"));
            geo.setReverse(extractJsonValue(jsonResponse, "reverse"));
            geo.setQuery(extractJsonValue(jsonResponse, "query"));
            geo.setMessage(extractJsonValue(jsonResponse, "message"));

            // 解析数值字段
            String latStr = extractJsonValue(jsonResponse, "lat");
            if (latStr != null && !latStr.isEmpty()) {
                try {
                    geo.setLat(Double.parseDouble(latStr));
                } catch (NumberFormatException e) {
                    // 忽略解析错误
                }
            }

            String lonStr = extractJsonValue(jsonResponse, "lon");
            if (lonStr != null && !lonStr.isEmpty()) {
                try {
                    geo.setLon(Double.parseDouble(lonStr));
                } catch (NumberFormatException e) {
                    // 忽略解析错误
                }
            }

            String offsetStr = extractJsonValue(jsonResponse, "offset");
            if (offsetStr != null && !offsetStr.isEmpty()) {
                try {
                    geo.setOffset(Integer.parseInt(offsetStr));
                } catch (NumberFormatException e) {
                    // 忽略解析错误
                }
            }

            // 解析布尔字段
            String mobileStr = extractJsonValue(jsonResponse, "mobile");
            if (mobileStr != null && !mobileStr.isEmpty()) {
                geo.setMobile(Boolean.parseBoolean(mobileStr));
            }

            String proxyStr = extractJsonValue(jsonResponse, "proxy");
            if (proxyStr != null && !proxyStr.isEmpty()) {
                geo.setProxy(Boolean.parseBoolean(proxyStr));
            }

            String hostingStr = extractJsonValue(jsonResponse, "hosting");
            if (hostingStr != null && !hostingStr.isEmpty()) {
                geo.setHosting(Boolean.parseBoolean(hostingStr));
            }

            return geo;

        } catch (Exception e) {
            // 解析失败时返回错误对象
            IPGeolocation errorGeo = new IPGeolocation();
            errorGeo.setStatus("fail");
            errorGeo.setMessage("JSON parsing failed: " + e.getMessage());
            return errorGeo;
        }
    }

    /**
     * 从JSON字符串中提取指定字段的值
     *
     * @param json JSON字符串
     * @param fieldName 字段名
     * @return 字段值，如果不存在则返回null
     */
    private static String extractJsonValue(String json, String fieldName) {
        String pattern = "\"" + fieldName + "\":\"([^\"]*)\"";
        Pattern p = Pattern.compile(pattern);
        Matcher m = p.matcher(json);

        if (m.find()) {
            return m.group(1);
        }

        // 尝试匹配数值字段（不带引号）
        pattern = "\"" + fieldName + "\":([^,\\s}]+)";
        p = Pattern.compile(pattern);
        m = p.matcher(json);

        if (m.find()) {
            return m.group(1);
        }

        return null;
    }

}